Add feature filter usage tracing

.gitignore

@@ -411,3 +411,7 @@ types/
 
 # examples
 examples/package-lock.json
+
+# cert
+*.cert
+*.key

package.json

@@ -52,7 +52,8 @@
     "sinon": "^15.2.0",
     "tslib": "^2.6.0",
     "typescript": "^5.6.3",
-    "uuid": "^9.0.1"
+    "uuid": "^9.0.1",
+    "selfsigned": "^2.4.1"
   },
   "dependencies": {
     "@azure/app-configuration": "^1.6.1",

src/AzureAppConfigurationImpl.ts

@@ -9,10 +9,11 @@ import { IKeyValueAdapter } from "./IKeyValueAdapter.js";
 import { JsonKeyValueAdapter } from "./JsonKeyValueAdapter.js";
 import { DEFAULT_REFRESH_INTERVAL_IN_MS, MIN_REFRESH_INTERVAL_IN_MS } from "./RefreshOptions.js";
 import { Disposable } from "./common/disposable.js";
-import { FEATURE_FLAGS_KEY_NAME, FEATURE_MANAGEMENT_KEY_NAME } from "./featureManagement/constants.js";
+import { FEATURE_FLAGS_KEY_NAME, FEATURE_MANAGEMENT_KEY_NAME, CONDITIONS_KEY_NAME, CLIENT_FILTERS_KEY_NAME, NAME_KEY_NAME } from "./featureManagement/constants.js";
 import { AzureKeyVaultKeyValueAdapter } from "./keyvault/AzureKeyVaultKeyValueAdapter.js";
 import { RefreshTimer } from "./refresh/RefreshTimer.js";
 import { getConfigurationSettingWithTrace, listConfigurationSettingsWithTrace, requestTracingEnabled } from "./requestTracing/utils.js";
+import { FeatureFlagTracingOptions } from "./requestTracing/FeatureFlagTracingOptions.js";
 import { KeyFilter, LabelFilter, SettingSelector } from "./types.js";
 
 type PagedSettingSelector = SettingSelector & {
@@ -38,6 +39,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
     #client: AppConfigurationClient;
     #options: AzureAppConfigurationOptions | undefined;
     #isInitialLoadCompleted: boolean = false;
+    #featureFlagTracing: FeatureFlagTracingOptions = new FeatureFlagTracingOptions();
 
     // Refresh
     #refreshInterval: number = DEFAULT_REFRESH_INTERVAL_IN_MS;
@@ -173,7 +175,8 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
         return {
             requestTracingEnabled: this.#requestTracingEnabled,
             initialLoadCompleted: this.#isInitialLoadCompleted,
-            appConfigOptions: this.#options
+            appConfigOptions: this.#options,
+            featureFlagTracingOptions: this.#featureFlagTracing
         };
     }
 
@@ -255,8 +258,7 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
     }
 
     async #loadFeatureFlags() {
-        // Temporary map to store feature flags, key is the key of the setting, value is the raw value of the setting
-        const featureFlagsMap = new Map<string, any>();
+        const featureFlagSettings: ConfigurationSetting[] = [];
         for (const selector of this.#featureFlagSelectors) {
             const listOptions: ListConfigurationSettingsOptions = {
                 keyFilter: `${featureFlagPrefix}${selector.keyFilter}`,
@@ -273,15 +275,19 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
                 pageEtags.push(page.etag ?? "");
                 for (const setting of page.items) {
                     if (isFeatureFlag(setting)) {
-                        featureFlagsMap.set(setting.key, setting.value);
+                        featureFlagSettings.push(setting);
                     }
                 }
             }
             selector.pageEtags = pageEtags;
         }
 
+        this.#featureFlagTracing.resetFeatureFlagTracing();
+
         // parse feature flags
-        const featureFlags = Array.from(featureFlagsMap.values()).map(rawFlag => JSON.parse(rawFlag));
+        const featureFlags = await Promise.all(
+            featureFlagSettings.map(setting => this.#parseFeatureFlag(setting))
+        );
 
         // feature_management is a reserved key, and feature_flags is an array of feature flags
         this.#configMap.set(FEATURE_MANAGEMENT_KEY_NAME, { [FEATURE_FLAGS_KEY_NAME]: featureFlags });
@@ -532,6 +538,22 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
         }
         return response;
     }
+
+    async #parseFeatureFlag(setting: ConfigurationSetting<string>): Promise<any> {
+        const rawFlag = setting.value;
+        if (rawFlag === undefined) {
+            throw new Error("The value of configuration setting cannot be undefined.");
+        }
+        const featureFlag = JSON.parse(rawFlag);
+
+        if (featureFlag[CONDITIONS_KEY_NAME] && featureFlag[CONDITIONS_KEY_NAME][CLIENT_FILTERS_KEY_NAME]) {
+            for (const filter of featureFlag[CONDITIONS_KEY_NAME][CLIENT_FILTERS_KEY_NAME]) {
+                this.#featureFlagTracing.updateFeatureFilterTracing(filter[NAME_KEY_NAME]);
+            }
+        }
+
+        return featureFlag;
+    }
 }
 
 function getValidSelectors(selectors: SettingSelector[]): SettingSelector[] {

src/featureManagement/constants.ts

@@ -2,4 +2,10 @@
 // Licensed under the MIT license.
 
 export const FEATURE_MANAGEMENT_KEY_NAME = "feature_management";
-export const FEATURE_FLAGS_KEY_NAME = "feature_flags";
+export const FEATURE_FLAGS_KEY_NAME = "feature_flags";
+export const CONDITIONS_KEY_NAME = "conditions";
+export const CLIENT_FILTERS_KEY_NAME = "client_filters";
+export const NAME_KEY_NAME = "name";
+
+export const TIME_WINDOW_FILTER_NAMES = ["TimeWindow", "Microsoft.TimeWindow", "TimeWindowFilter", "Microsoft.TimeWindowFilter"];
+export const TARGETING_FILTER_NAMES = ["Targeting", "Microsoft.Targeting", "TargetingFilter", "Microsoft.TargetingFilter"];

src/requestTracing/FeatureFlagTracingOptions.ts

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { TIME_WINDOW_FILTER_NAMES, TARGETING_FILTER_NAMES } from "../featureManagement/constants";
+import { CUSTOM_FILTER_KEY, TIME_WINDOW_FILTER_KEY, TARGETING_FILTER_KEY, DELIMITER } from "./constants";
+
+/**
+ * Tracing for tracking feature flag usage.
+ */
+export class FeatureFlagTracingOptions {
+    /**
+     * Built-in feature filter usage.
+     */
+    usesCustomFilter: boolean = false;
+    usesTimeWindowFilter: boolean = false;
+    usesTargetingFilter: boolean = false;
+
+    resetFeatureFlagTracing(): void {
+        this.usesCustomFilter = false;
+        this.usesTimeWindowFilter = false;
+        this.usesTargetingFilter = false;
+    }
+
+    updateFeatureFilterTracing(filterName: string): void {
+        if (TIME_WINDOW_FILTER_NAMES.some(name => name === filterName)) {
+            this.usesTimeWindowFilter = true;
+        } else if (TARGETING_FILTER_NAMES.some(name => name === filterName)) {
+            this.usesTargetingFilter = true;
+        } else {
+            this.usesCustomFilter = true;
+        }
+    }
+
+    usesAnyFeatureFilter(): boolean {
+        return this.usesCustomFilter || this.usesTimeWindowFilter || this.usesTargetingFilter;
+    }
+
+    createFeatureFiltersString(): string {
+        if (!this.usesAnyFeatureFilter()) {
+            return "";
+        }
+
+        let result: string = "";
+
+        if (this.usesCustomFilter) {
+            result += CUSTOM_FILTER_KEY;
+        }
+
+        if (this.usesTimeWindowFilter) {
+            if (result !== "") {
+                result += DELIMITER;
+            }
+            result += TIME_WINDOW_FILTER_KEY;
+        }
+
+        if (this.usesTargetingFilter) {
+            if (result !== "") {
+                result += DELIMITER;
+            }
+            result += TARGETING_FILTER_KEY;
+        }
+
+        return result;
+    }
+}

src/requestTracing/constants.ts

@@ -46,3 +46,11 @@ export enum RequestType {
 
 // Tag names
 export const KEY_VAULT_CONFIGURED_TAG = "UsesKeyVault";
+
+// Feature Flag Usage Tracing
+export const FEATURE_FILTER_TYPE_KEY = "Filter";
+export const CUSTOM_FILTER_KEY = "CSTM";
+export const TIME_WINDOW_FILTER_KEY = "TIME";
+export const TARGETING_FILTER_KEY = "TRGT";
+
+export const DELIMITER = "+";

src/requestTracing/utils.ts

@@ -3,13 +3,15 @@
 
 import { AppConfigurationClient, ConfigurationSettingId, GetConfigurationSettingOptions, ListConfigurationSettingsOptions } from "@azure/app-configuration";
 import { AzureAppConfigurationOptions } from "../AzureAppConfigurationOptions.js";
+import { FeatureFlagTracingOptions } from "./FeatureFlagTracingOptions.js";
 import {
     AZURE_FUNCTION_ENV_VAR,
     AZURE_WEB_APP_ENV_VAR,
     CONTAINER_APP_ENV_VAR,
     DEV_ENV_VAL,
     ENV_AZURE_APP_CONFIGURATION_TRACING_DISABLED,
     ENV_KEY,
+    FEATURE_FILTER_TYPE_KEY,
     HOST_TYPE_KEY,
     HostType,
     KEY_VAULT_CONFIGURED_TAG,
@@ -28,17 +30,18 @@ export function listConfigurationSettingsWithTrace(
         requestTracingEnabled: boolean;
         initialLoadCompleted: boolean;
         appConfigOptions: AzureAppConfigurationOptions | undefined;
+        featureFlagTracingOptions: FeatureFlagTracingOptions | undefined;
     },
     client: AppConfigurationClient,
     listOptions: ListConfigurationSettingsOptions
 ) {
-    const { requestTracingEnabled, initialLoadCompleted, appConfigOptions } = requestTracingOptions;
+    const { requestTracingEnabled, initialLoadCompleted, appConfigOptions, featureFlagTracingOptions } = requestTracingOptions;
 
     const actualListOptions = { ...listOptions };
     if (requestTracingEnabled) {
         actualListOptions.requestOptions = {
             customHeaders: {
-                [CORRELATION_CONTEXT_HEADER_NAME]: createCorrelationContextHeader(appConfigOptions, initialLoadCompleted)
+                [CORRELATION_CONTEXT_HEADER_NAME]: createCorrelationContextHeader(appConfigOptions, featureFlagTracingOptions, initialLoadCompleted)
             }
         };
     }
@@ -51,26 +54,27 @@ export function getConfigurationSettingWithTrace(
         requestTracingEnabled: boolean;
         initialLoadCompleted: boolean;
         appConfigOptions: AzureAppConfigurationOptions | undefined;
+        featureFlagTracingOptions: FeatureFlagTracingOptions | undefined;
     },
     client: AppConfigurationClient,
     configurationSettingId: ConfigurationSettingId,
     getOptions?: GetConfigurationSettingOptions,
 ) {
-    const { requestTracingEnabled, initialLoadCompleted, appConfigOptions } = requestTracingOptions;
+    const { requestTracingEnabled, initialLoadCompleted, appConfigOptions, featureFlagTracingOptions } = requestTracingOptions;
     const actualGetOptions = { ...getOptions };
 
     if (requestTracingEnabled) {
         actualGetOptions.requestOptions = {
             customHeaders: {
-                [CORRELATION_CONTEXT_HEADER_NAME]: createCorrelationContextHeader(appConfigOptions, initialLoadCompleted)
+                [CORRELATION_CONTEXT_HEADER_NAME]: createCorrelationContextHeader(appConfigOptions, featureFlagTracingOptions, initialLoadCompleted)
             }
         };
     }
 
     return client.getConfigurationSetting(configurationSettingId, actualGetOptions);
 }
 
-export function createCorrelationContextHeader(options: AzureAppConfigurationOptions | undefined, isInitialLoadCompleted: boolean): string {
+export function createCorrelationContextHeader(options: AzureAppConfigurationOptions | undefined, featureFlagTracing: FeatureFlagTracingOptions | undefined, isInitialLoadCompleted: boolean): string {
     /*
     RequestType: 'Startup' during application starting up, 'Watch' after startup completed.
     Host: identify with defined envs
@@ -81,6 +85,7 @@ export function createCorrelationContextHeader(options: AzureAppConfigurationOpt
     keyValues.set(REQUEST_TYPE_KEY, isInitialLoadCompleted ? RequestType.WATCH : RequestType.STARTUP);
     keyValues.set(HOST_TYPE_KEY, getHostType());
     keyValues.set(ENV_KEY, isDevEnvironment() ? DEV_ENV_VAL : undefined);
+    keyValues.set(FEATURE_FILTER_TYPE_KEY, featureFlagTracing?.usesAnyFeatureFilter() ? featureFlagTracing.createFeatureFiltersString() : undefined);
 
     const tags: string[] = [];
     if (options?.keyVaultOptions) {

test/integration.test.ts

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as chai from "chai";
+import * as chaiAsPromised from "chai-as-promised";
+chai.use(chaiAsPromised);
+const expect = chai.expect;
+import { createMockedConnectionString, createMockedFeatureFlag, HttpRequestHeadersPolicy, sleepInMs } from "./utils/testHelper.js";
+import { mockServerEndpoint, startMockServer, closeMockServer } from "./utils/integrationTestHelper.js";
+import { load } from "./exportedApi.js";
+
+describe("integration test", function () {
+    this.timeout(15000);
+
+    const headerPolicy = new HttpRequestHeadersPolicy();
+    const position: "perCall" | "perRetry" = "perCall";
+    const clientOptions = {
+        retryOptions: {
+            maxRetries: 0 // save time
+        },
+        allowInsecureConnection: true,
+        additionalPolicies: [{
+            policy: headerPolicy,
+            position
+        }]
+    };
+
+    it("should have filter type in correlation-context header if feature flags use feature filters", async () => {
+        // We are using self-signed certificate
+        process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+
+        startMockServer([
+            createMockedFeatureFlag("Alpha_1", { conditions: { client_filters: [ { name: "Microsoft.TimeWindow" } ] } }),
+            createMockedFeatureFlag("Alpha_2", { conditions: { client_filters: [ { name: "Microsoft.Targeting" } ] } }),
+            createMockedFeatureFlag("Alpha_3", { conditions: { client_filters: [ { name: "CustomFilter" } ] } })
+        ]);
+
+        const settings = await load(createMockedConnectionString(mockServerEndpoint), {
+            clientOptions,
+            featureFlagOptions: {
+                enabled: true,
+                selectors: [ {keyFilter: "*"} ],
+                refresh: {
+                    enabled: true,
+                    refreshIntervalInMs: 1000
+                }
+            }
+        });
+        expect(headerPolicy.headers).not.undefined;
+        let correlationContext = headerPolicy.headers.get("Correlation-Context");
+        expect(correlationContext).not.undefined;
+        expect(correlationContext.includes("RequestType=Startup")).eq(true);
+
+        await sleepInMs(1000 + 1);
+        try {
+            await settings.refresh();
+        } catch (e) { /* empty */ }
+        expect(headerPolicy.headers).not.undefined;
+        correlationContext = headerPolicy.headers.get("Correlation-Context");
+        expect(correlationContext).not.undefined;
+        expect(correlationContext.includes("RequestType=Watch")).eq(true);
+        expect(correlationContext.includes("Filter=CSTM+TIME+TRGT")).eq(true);
+
+        closeMockServer();
+    });
+});