@fluidframework/telemetry-utils 2.74.0 → 2.81.0-374083

package/src/index.ts

@@ -98,4 +98,4 @@ export type {
 	TelemetryEventCategory,
 } from "./telemetryTypes.js";
 export { TelemetryEventBatcher } from "./telemetryEventBatcher.js";
-export { validateLayerCompatibility } from "./layerCompatError.js";
+export { allowIncompatibleLayersKey, validateLayerCompatibility } from "./layerCompatError.js";

package/src/layerCompatError.ts

@@ -11,13 +11,45 @@ import {
 } from "@fluid-internal/client-utils";
 import type { IErrorBase } from "@fluidframework/core-interfaces";
 
+import type { MonitoringContext } from "./config.js";
 import { LayerIncompatibilityError } from "./error.js";
-import type { ITelemetryLoggerExt } from "./telemetryTypes.js";
+
+/**
+ * The config key to disable layer compatibility validation.
+ * @internal
+ */
+export const allowIncompatibleLayersKey = "Fluid.AllowIncompatibleLayers";
+
+/**
+ * Tracks whether the event is logged when failing on layer incompatibility is bypassed via global config.
+ * This is used to ensure that the bypass event is only logged once per session so it does not flood telemetry.
+ */
+let globalBypassLogged = false;
+
+/**
+ * Tracks whether the event is logged when failing on layer incompatibility is bypassed due to missing
+ * compatibility details for each layer pair.
+ * This is used to ensure that the bypass event is only logged once per layer pair so it does not flood telemetry.
+ */
+const strictCheckBypassLoggedForPair: Set<string> = new Set<string>();
 
 /**
  * Validates the compatibility between two layers using their compatibility details and support requirements.
- * If the layers are incompatible, it logs an "LayerIncompatibilityError" error event. It will also call the dispose
+ * If the layers are incompatible, it logs a "LayerIncompatibilityError" error event. It will also call the dispose
  * function with the error and throw the error.
+ * @param layer1 - The name of the first layer.
+ * @param layer2 - The name of the second layer.
+ * @param compatDetailsLayer1 - The compatibility details of the first layer.
+ * @param compatSupportRequirementsLayer1 - The support requirements that the second layer must meet to be compatible
+ * with the first layer.
+ * @param maybeCompatDetailsLayer2 - The compatibility details of the second layer. This can be undefined if the
+ * second layer does not provide compatibility details.
+ * @param disposeFn - A function that will be called with the error if the layers are incompatible.
+ * @param mc - The monitoring context for logging and reading configuration.
+ * @param strictCompatibilityCheck - If true, the function will use default compatibility details for the second layer if
+ * they are missing and use it for validation.
+ * If false, it will skip the compatibility check if the details are missing and just log an error.
+ * Defaults to false.
  *
  * @internal
  */
@@ -28,7 +60,8 @@ export function validateLayerCompatibility(
 	compatSupportRequirementsLayer1: ILayerCompatSupportRequirements,
 	maybeCompatDetailsLayer2: ILayerCompatDetails | undefined,
 	disposeFn: (error?: IErrorBase) => void,
-	logger: ITelemetryLoggerExt,
+	mc: MonitoringContext,
+	strictCompatibilityCheck: boolean = false,
 ): void {
 	const layerCheckResult = checkLayerCompatibility(
 		compatSupportRequirementsLayer1,
@@ -61,7 +94,47 @@ export function validateLayerCompatibility(
 				details: JSON.stringify(detailedProperties),
 			},
 		);
-		logger.sendErrorEvent(
+
+		if (mc.config.getBoolean(allowIncompatibleLayersKey) === true) {
+			// If the validation is explicitly disabled via config, do not fail. This config provides a way to bypass
+			// compatibility validation while this feature is being rolled out.
+			if (!globalBypassLogged) {
+				// This event is only logged once per session to avoid flooding telemetry.
+				globalBypassLogged = true;
+				mc.logger.sendTelemetryEvent(
+					{
+						eventName: "LayerIncompatibilityDetectedButBypassed",
+						reason: `${allowIncompatibleLayersKey} config is set to true`,
+					},
+					error,
+				);
+			}
+			return;
+		}
+
+		if (maybeCompatDetailsLayer2 === undefined && !strictCompatibilityCheck) {
+			// If there is no compatibility details for layer2 and strictCompatibilityCheck is false, do not fail.
+			// There can be a couple of scenarios where this can happen:
+			// 1. layer2's version is older than the version where compatibility enforcement was introduced. In this
+			//    case, the behavior is the same as before compatibility enforcement was introduced.
+			// 2. layer2 has a custom implementation which doesn't provide compatibility details. In this case,
+			//    we don't know for sure that it is incompatible. It may fail at a later point when it tries to use
+			//    some feature that the Runtime doesn't support.
+			if (!strictCheckBypassLoggedForPair.has(`${layer1}-${layer2}`)) {
+				// This event is only logged once per session per layer combination to avoid flooding telemetry.
+				strictCheckBypassLoggedForPair.add(`${layer1}-${layer2}`);
+				mc.logger.sendTelemetryEvent(
+					{
+						eventName: "LayerIncompatibilityDetectedButBypassed",
+						reason: `No compatibility details provided for ${layer2} and strictCompatibilityCheck is false`,
+					},
+					error,
+				);
+			}
+			return;
+		}
+
+		mc.logger.sendErrorEvent(
 			{
 				eventName: "LayerIncompatibilityError",
 			},

package/.eslintrc.cjs

@@ -1,11 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-module.exports = {
-	extends: [require.resolve("@fluidframework/eslint-config-fluid/strict"), "prettier"],
-	parserOptions: {
-		project: ["./tsconfig.json", "./src/test/tsconfig.json"],
-	},
-};