@fluidframework/telemetry-utils 2.0.0-internal.6.3.3 → 2.0.0-internal.7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/telemetry-utils",
-  "version": "2.0.0-internal.6.3.3",
+  "version": "2.0.0-internal.7.0.0",
   "description": "Collection of telemetry relates utilities for Fluid",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -39,22 +39,22 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": ">=2.0.0-internal.6.3.3 <2.0.0-internal.6.4.0",
-    "@fluidframework/core-interfaces": ">=2.0.0-internal.6.3.3 <2.0.0-internal.6.4.0",
-    "@fluidframework/core-utils": ">=2.0.0-internal.6.3.3 <2.0.0-internal.6.4.0",
-    "@fluidframework/protocol-definitions": "^1.1.0",
+    "@fluid-internal/client-utils": ">=2.0.0-internal.7.0.0 <2.0.0-internal.7.1.0",
+    "@fluidframework/core-interfaces": ">=2.0.0-internal.7.0.0 <2.0.0-internal.7.1.0",
+    "@fluidframework/core-utils": ">=2.0.0-internal.7.0.0 <2.0.0-internal.7.1.0",
+    "@fluidframework/protocol-definitions": "^3.0.0",
     "debug": "^4.1.1",
     "events": "^3.1.0",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
-    "@fluid-tools/build-cli": "^0.22.0",
+    "@fluid-tools/build-cli": "^0.24.0",
     "@fluidframework/build-common": "^2.0.0",
-    "@fluidframework/build-tools": "^0.22.0",
+    "@fluidframework/build-tools": "^0.24.0",
     "@fluidframework/eslint-config-fluid": "^2.1.0",
-    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.6.3.3 <2.0.0-internal.6.4.0",
-    "@fluidframework/telemetry-utils-previous": "npm:@fluidframework/telemetry-utils@2.0.0-internal.6.3.1",
-    "@microsoft/api-extractor": "^7.34.4",
+    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.7.0.0 <2.0.0-internal.7.1.0",
+    "@fluidframework/telemetry-utils-previous": "npm:@fluidframework/telemetry-utils@2.0.0-internal.6.3.0",
+    "@microsoft/api-extractor": "^7.37.0",
     "@types/debug": "^4.1.5",
     "@types/events": "^3.0.0",
     "@types/mocha": "^9.1.1",
@@ -71,7 +71,7 @@
     "prettier": "~2.6.2",
     "rimraf": "^4.4.0",
     "sinon": "^7.4.2",
-    "typescript": "~4.5.5"
+    "typescript": "~5.1.6"
   },
   "typeValidation": {
     "broken": {}

package/src/config.ts

@@ -77,10 +77,12 @@ function isPrimitiveType(type: string): type is PrimitiveTypeStrings {
 	switch (type) {
 		case "boolean":
 		case "number":
-		case "string":
+		case "string": {
 			return true;
-		default:
+		}
+		default: {
 			return false;
+		}
 	}
 }
 

package/src/error.ts

@@ -7,7 +7,7 @@ import {
 	FluidErrorTypes,
 	IGenericError,
 	IErrorBase,
-	ITelemetryProperties,
+	ITelemetryBaseProperties,
 	IUsageError,
 } from "@fluidframework/core-interfaces";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
@@ -23,6 +23,8 @@ import { IFluidErrorBase } from "./fluidErrorBase";
 
 /**
  * Generic wrapper for an unrecognized/uncategorized error object
+ *
+ * @internal
  */
 export class GenericError extends LoggingError implements IGenericError, IFluidErrorBase {
 	readonly errorType = FluidErrorTypes.genericError;
@@ -35,7 +37,7 @@ export class GenericError extends LoggingError implements IGenericError, IFluidE
 	 */
 	// TODO: Use `unknown` instead (API breaking change because error is not just an input parameter, but a public member of the class)
 	// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
-	constructor(message: string, public readonly error?: any, props?: ITelemetryProperties) {
+	constructor(message: string, public readonly error?: any, props?: ITelemetryBaseProperties) {
 		// Don't try to log the inner error
 		super(message, props, new Set(["error"]));
 	}
@@ -43,11 +45,13 @@ export class GenericError extends LoggingError implements IGenericError, IFluidE
 
 /**
  * Error indicating an API is being used improperly resulting in an invalid operation.
+ *
+ * @internal
  */
 export class UsageError extends LoggingError implements IUsageError, IFluidErrorBase {
 	readonly errorType = FluidErrorTypes.usageError;
 
-	constructor(message: string, props?: ITelemetryProperties) {
+	constructor(message: string, props?: ITelemetryBaseProperties) {
 		super(message, { ...props, usageError: true });
 	}
 }
@@ -55,12 +59,14 @@ export class UsageError extends LoggingError implements IUsageError, IFluidError
 /**
  * DataCorruptionError indicates that we encountered definitive evidence that the data at rest
  * backing this container is corrupted, and this container would never be expected to load properly again
+ *
+ * @internal
  */
 export class DataCorruptionError extends LoggingError implements IErrorBase, IFluidErrorBase {
 	readonly errorType = FluidErrorTypes.dataCorruptionError;
 	readonly canRetry = false;
 
-	constructor(message: string, props: ITelemetryProperties) {
+	constructor(message: string, props: ITelemetryBaseProperties) {
 		super(message, { ...props, dataProcessingError: 1 });
 	}
 }
@@ -73,6 +79,8 @@ export class DataCorruptionError extends LoggingError implements IErrorBase, IFl
  * The error will often originate in the dataStore or DDS implementation that is responding to incoming changes.
  * This differs from {@link DataCorruptionError} in that this may be a transient error that will not repro in another
  * client or session.
+ *
+ * @internal
  */
 export class DataProcessingError extends LoggingError implements IErrorBase, IFluidErrorBase {
 	/**
@@ -82,8 +90,8 @@ export class DataProcessingError extends LoggingError implements IErrorBase, IFl
 
 	public readonly canRetry = false;
 
-	private constructor(errorMessage: string) {
-		super(errorMessage);
+	private constructor(errorMessage: string, props?: ITelemetryBaseProperties) {
+		super(errorMessage, props);
 	}
 
 	/**
@@ -93,7 +101,7 @@ export class DataProcessingError extends LoggingError implements IErrorBase, IFl
 		errorMessage: string,
 		dataProcessingCodepath: string,
 		sequencedMessage?: ISequencedDocumentMessage,
-		props: ITelemetryProperties = {},
+		props: ITelemetryBaseProperties = {},
 	): IFluidErrorBase {
 		const dataProcessingError = DataProcessingError.wrapIfUnrecognized(
 			errorMessage,

package/src/errorLogging.ts

@@ -27,6 +27,8 @@ const isRegularObject = (value: unknown): boolean => {
 
 /**
  * Inspect the given error for common "safe" props and return them.
+ *
+ * @internal
  */
 export function extractLogSafeErrorProperties(
 	error: unknown,
@@ -95,6 +97,8 @@ function copyProps(
 
 /**
  * Metadata to annotate an error object when annotating or normalizing it
+ *
+ * @internal
  */
 export interface IFluidErrorAnnotations {
 	/**
@@ -121,6 +125,8 @@ function patchLegacyError(
  * @returns A valid Fluid Error with any provided annotations applied
  * @param error - The error to normalize
  * @param annotations - Annotations to apply to the normalized error
+ *
+ * @internal
  */
 export function normalizeError(
 	error: unknown,
@@ -190,6 +196,8 @@ let stackPopulatedOnCreation: boolean | undefined;
  * For such cases it's better to not read stack property right away, but rather delay it until / if it's needed
  * Some browsers will populate stack right away, others require throwing Error, so we do auto-detection on the fly.
  * @returns Error object that has stack populated.
+ *
+ * @internal
  */
 export function generateErrorWithStack(): Error {
 	const err = new Error("<<generated stack>>");
@@ -209,6 +217,12 @@ export function generateErrorWithStack(): Error {
 	}
 }
 
+/**
+ * Generate a stack at this callsite as if an error were thrown from here.
+ * @returns the callstack (does not throw)
+ *
+ * @internal
+ */
 export function generateStack(): string | undefined {
 	return generateErrorWithStack().stack;
 }
@@ -219,6 +233,8 @@ export function generateStack(): string | undefined {
  * @param innerError - An error from untrusted/unknown origins
  * @param newErrorFn - callback that will create a new error given the original error's message
  * @returns A new error object "wrapping" the given error
+ *
+ * @internal
  */
 export function wrapError<T extends LoggingError>(
 	innerError: unknown,
@@ -258,6 +274,8 @@ export function wrapError<T extends LoggingError>(
  * The same as wrapError, but also logs the innerError, including the wrapping error's instance ID.
  *
  * @typeParam T - The kind of wrapper error to create.
+ *
+ * @internal
  */
 export function wrapErrorAndLog<T extends LoggingError>(
 	innerError: unknown,
@@ -284,8 +302,15 @@ export function wrapErrorAndLog<T extends LoggingError>(
 	return newError;
 }
 
-function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string): void {
-	// supposedly setting stack on an Error can throw.
+/**
+ * Attempts to overwrite the error's stack
+ *
+ * There have been reports of certain JS environments where overwriting stack will throw.
+ * If that happens, this adds the given stack as the telemetry property "stack2"
+ *
+ * @internal
+ */
+export function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string): void {
 	try {
 		Object.assign(error, { stack });
 	} catch {
@@ -297,6 +322,8 @@ function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string): v
  * True for any error object that is an (optionally normalized) external error
  * False for any error we created and raised within the FF codebase via LoggingError base class,
  * or wrapped in a well-known error type
+ *
+ * @internal
  */
 export function isExternalError(error: unknown): boolean {
 	// LoggingErrors are an internal FF error type. However, an external error can be converted
@@ -322,8 +349,8 @@ export function isTaggedTelemetryPropertyValue(
 
 /**
  * Filter serializable telemetry properties
- * @param x - any telemetry prop
- * @returns - as-is if x is primitive. returns stringified if x is an array of primitive.
+ * @param x - Any telemetry prop
+ * @returns As-is if x is primitive. returns stringified if x is an array of primitive.
  * otherwise returns null since this is what we support at the moment.
  */
 function filterValidTelemetryProps(x: unknown, key: string): TelemetryBaseEventPropertyType {
@@ -344,12 +371,15 @@ function isTelemetryEventPropertyValue(x: unknown): x is TelemetryBaseEventPrope
 		case "string":
 		case "number":
 		case "boolean":
-		case "undefined":
+		case "undefined": {
 			return true;
-		default:
+		}
+		default: {
 			return false;
+		}
 	}
 }
+
 /**
  * Walk an object's enumerable properties to find those fit for telemetry.
  */
@@ -364,14 +394,12 @@ function getValidTelemetryProps(obj: object, keysToOmit: Set<string>): ITelemetr
 			| Tagged<TelemetryEventPropertyTypeExt>;
 
 		// ensure only valid props get logged, since props of logging error could be in any shape
-		if (isTaggedTelemetryPropertyValue(val)) {
-			props[key] = {
-				value: filterValidTelemetryProps(val.value, key),
-				tag: val.tag,
-			};
-		} else {
-			props[key] = filterValidTelemetryProps(val, key);
-		}
+		props[key] = isTaggedTelemetryPropertyValue(val)
+			? {
+					value: filterValidTelemetryProps(val.value, key),
+					tag: val.tag,
+			  }
+			: filterValidTelemetryProps(val, key);
 	}
 	return props;
 }
@@ -382,6 +410,8 @@ function getValidTelemetryProps(obj: object, keysToOmit: Set<string>): ITelemetr
  * Avoids runtime errors with circular references.
  * Not ideal, as will cut values that are not necessarily circular references.
  * Could be improved by implementing Node's util.inspect() for browser (minus all the coloring code)
+ *
+ * @internal
  */
 // TODO: Use `unknown` instead (API breaking change)
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -405,6 +435,8 @@ export const getCircularReplacer = (): ((key: string, value: unknown) => any) =>
  * will be logged in accordance with their tag, if present.
  *
  * PLEASE take care to avoid setting sensitive data on this object without proper tagging!
+ *
+ * @internal
  */
 export class LoggingError
 	extends Error
@@ -450,7 +482,7 @@ export class LoggingError
 	/**
 	 * Determines if a given object is an instance of a LoggingError
 	 * @param object - any object
-	 * @returns - true if the object is an instance of a LoggingError, false if not.
+	 * @returns true if the object is an instance of a LoggingError, false if not.
 	 */
 	public static typeCheck(object: unknown): object is LoggingError {
 		if (typeof object === "object" && object !== null) {
@@ -487,8 +519,16 @@ export class LoggingError
 
 /**
  * The Error class used when normalizing an external error
+ *
+ * @internal
  */
 export const NORMALIZED_ERROR_TYPE = "genericError";
+
+/**
+ * Subclass of LoggingError returned by normalizeError
+ *
+ * @internal
+ */
 class NormalizedLoggingError extends LoggingError {
 	// errorType "genericError" is used as a default value throughout the code.
 	// Note that this matches ContainerErrorType/DriverErrorType's genericError

package/src/events.ts

@@ -3,6 +3,8 @@
  * Licensed under the MIT License.
  */
 
+// False positive: this is an import from the `events` package, not from Node.
+// eslint-disable-next-line unicorn/prefer-node-protocol
 import { EventEmitter } from "events";
 import { ITelemetryLoggerExt } from "./telemetryTypes";
 

package/src/index.ts

@@ -31,6 +31,7 @@ export {
 	LoggingError,
 	NORMALIZED_ERROR_TYPE,
 	normalizeError,
+	overwriteStack,
 	wrapError,
 	wrapErrorAndLog,
 } from "./errorLogging";

package/src/logger.ts

@@ -14,6 +14,7 @@ import {
 	LogLevel,
 	Tagged,
 	ITelemetryBaseProperties,
+	TelemetryBaseEventPropertyType,
 } from "@fluidframework/core-interfaces";
 import { IsomorphicPerformance, performance } from "@fluid-internal/client-utils";
 import { CachedConfigProvider, loggerIsMonitoringContext, mixinMonitoringContext } from "./config";
@@ -304,26 +305,30 @@ export class TaggedLoggerAdapter implements ITelemetryBaseLogger {
 					? taggableProp
 					: { value: taggableProp, tag: undefined };
 			switch (tag) {
-				case undefined:
+				case undefined: {
 					// No tag means we can log plainly
 					newEvent[key] = value;
 					break;
+				}
 				case "PackageData": // For back-compat
-				case TelemetryDataTag.CodeArtifact:
+				case TelemetryDataTag.CodeArtifact: {
 					// For Microsoft applications, CodeArtifact is safe for now
 					// (we don't load 3P code in 1P apps)
 					newEvent[key] = value;
 					break;
-				case TelemetryDataTag.UserData:
+				}
+				case TelemetryDataTag.UserData: {
 					// Strip out anything tagged explicitly as UserData.
 					// Alternate strategy would be to hash these props
 					newEvent[key] = "REDACTED (UserData)";
 					break;
-				default:
+				}
+				default: {
 					// If we encounter a tag we don't recognize
 					// then we must assume we should scrub.
 					newEvent[key] = "REDACTED (unknown tag)";
 					break;
+				}
 			}
 		}
 		this.logger.send(newEvent);
@@ -403,11 +408,7 @@ export class ChildLogger extends TelemetryLogger {
 			return child;
 		}
 
-		return new ChildLogger(
-			baseLogger ? baseLogger : { send(): void {} },
-			namespace,
-			properties,
-		);
+		return new ChildLogger(baseLogger ?? { send(): void {} }, namespace, properties);
 	}
 
 	private constructor(
@@ -488,7 +489,7 @@ export class MultiSinkLogger extends TelemetryLogger {
 		loggers: ITelemetryBaseLogger[] = [],
 		tryInheritProperties?: true,
 	) {
-		let realProperties = properties !== undefined ? { ...properties } : undefined;
+		let realProperties = properties === undefined ? undefined : { ...properties };
 		if (tryInheritProperties === true) {
 			const merge = (realProperties ??= {});
 			loggers
@@ -629,8 +630,7 @@ export class PerformanceEvent {
 			this.reportEvent("start");
 		}
 
-		// eslint-disable-next-line unicorn/no-null
-		if (typeof window === "object" && window != null && window.performance?.mark) {
+		if (typeof window === "object" && window?.performance?.mark) {
 			this.startMark = `${event.eventName}-start`;
 			window.performance.mark(this.startMark);
 		}
@@ -768,54 +768,85 @@ function convertToBasePropertyTypeUntagged(
 		case "string":
 		case "number":
 		case "boolean":
-		case "undefined":
+		case "undefined": {
 			return x;
-		case "object":
+		}
+		case "object": {
 			// We assume this is an array or flat object based on the input types
 			return JSON.stringify(x);
-		default:
+		}
+		default: {
 			// should never reach this case based on the input types
 			console.error(
 				`convertToBasePropertyTypeUntagged: INVALID PROPERTY (typed as ${typeof x})`,
 			);
 			return `INVALID PROPERTY (typed as ${typeof x})`;
+		}
 	}
 }
 
 export const tagData = <
 	T extends TelemetryDataTag,
-	V extends Record<string, TelemetryEventPropertyTypeExt>,
+	V extends Record<
+		string,
+		TelemetryBaseEventPropertyType | (() => TelemetryBaseEventPropertyType)
+	>,
 >(
 	tag: T,
 	values: V,
 ): {
 	[P in keyof V]:
-		| {
-				value: Exclude<V[P], undefined>;
-				tag: T;
-		  }
+		| (V[P] extends () => TelemetryBaseEventPropertyType
+				? () => {
+						value: ReturnType<V[P]>;
+						tag: T;
+				  }
+				: {
+						value: Exclude<V[P], undefined>;
+						tag: T;
+				  })
 		| (V[P] extends undefined ? undefined : never);
 } =>
-	(Object.entries(values) as [keyof V, V[keyof V]][])
-		.filter((e): e is [keyof V, Exclude<V[keyof V], undefined>] => e[1] !== undefined)
-		// eslint-disable-next-line unicorn/no-array-reduce
-		.reduce<{
-			[P in keyof V]:
-				| (V[P] extends undefined ? undefined : never)
-				| { value: Exclude<V[P], undefined>; tag: T };
-		}>((pv, cv) => {
-			pv[cv[0]] = { tag, value: cv[1] };
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+	Object.entries(values)
+		.filter((e) => e[1] !== undefined)
+		// eslint-disable-next-line unicorn/no-array-reduce, unicorn/prefer-object-from-entries
+		.reduce((pv, cv) => {
+			const [key, value] = cv;
+			// The ternary form is less legible in this case.
+			// eslint-disable-next-line unicorn/prefer-ternary
+			if (typeof value === "function") {
+				// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+				pv[key] = () => {
+					return { tag, value: value() };
+				};
+			} else {
+				pv[key] = { tag, value };
+			}
 			return pv;
-			// eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any
-		}, {} as any);
+		}, {}) as ReturnType<typeof tagData>;
 
-export const tagCodeArtifacts = <T extends Record<string, TelemetryEventPropertyTypeExt>>(
+/**
+ * Helper function to tag telemetry properties as CodeArtifacts. It supports properties of type
+ * TelemetryBaseEventPropertyType as well as getters that return TelemetryBaseEventPropertyType.
+ */
+export const tagCodeArtifacts = <
+	T extends Record<
+		string,
+		TelemetryBaseEventPropertyType | (() => TelemetryBaseEventPropertyType)
+	>,
+>(
 	values: T,
 ): {
 	[P in keyof T]:
-		| {
-				value: Exclude<T[P], undefined>;
-				tag: TelemetryDataTag.CodeArtifact;
-		  }
+		| (T[P] extends () => TelemetryBaseEventPropertyType
+				? () => {
+						value: ReturnType<T[P]>;
+						tag: TelemetryDataTag.CodeArtifact;
+				  }
+				: {
+						value: Exclude<T[P], undefined>;
+						tag: TelemetryDataTag.CodeArtifact;
+				  })
 		| (T[P] extends undefined ? undefined : never);
-} => tagData(TelemetryDataTag.CodeArtifact, values);
+} => tagData<TelemetryDataTag.CodeArtifact, T>(TelemetryDataTag.CodeArtifact, values);

package/src/utils.ts

@@ -13,7 +13,7 @@ import {
  * @param condition - The condition to attest too
  * @param logger - The logger to log with
  * @param event - The string or event to log
- * @returns - The outcome of the condition
+ * @returns The outcome of the condition
  */
 export function logIfFalse(
 	condition: unknown,