@fluidframework/telemetry-utils 2.0.0-internal.6.1.1 → 2.0.0-internal.6.3.0

package/src/config.ts

@@ -50,11 +50,12 @@ const NullConfigProvider: IConfigProviderBase = {
 export const inMemoryConfigProvider = (storage: Storage | undefined): IConfigProviderBase => {
 	if (storage !== undefined && storage !== null) {
 		return new CachedConfigProvider(undefined, {
-			getRawConfig: (name: string) => {
+			getRawConfig: (name: string): ConfigTypes | undefined => {
 				try {
 					return stronglyTypedParse(storage.getItem(name) ?? undefined)?.raw;
-				} catch {}
-				return undefined;
+				} catch {
+					return undefined;
+				}
 			},
 		});
 	}
@@ -104,7 +105,7 @@ function stronglyTypedParse(input: ConfigTypes): StronglyTypedValue | undefined
 	// holds strings
 	if (typeof input === "string") {
 		try {
-			output = JSON.parse(input);
+			output = JSON.parse(input) as ConfigTypes;
 			// we succeeded in parsing, but we don't support parsing
 			// for any object as we can't do it type safely
 			// so in this case, the default return will be string
@@ -113,7 +114,9 @@ function stronglyTypedParse(input: ConfigTypes): StronglyTypedValue | undefined
 			// a false sense of security by just
 			// casting.
 			defaultReturn = { raw: input, string: input };
-		} catch {}
+		} catch {
+			// No-op
+		}
 	}
 
 	if (output === undefined) {
@@ -144,7 +147,9 @@ function stronglyTypedParse(input: ConfigTypes): StronglyTypedValue | undefined
 	return defaultReturn;
 }
 
-/** `sessionStorage` is undefined in some environments such as Node and web pages with session storage disabled */
+/**
+ * `sessionStorage` is undefined in some environments such as Node and web pages with session storage disabled.
+ */
 const safeSessionStorage = (): Storage | undefined => {
 	// For some configurations accessing "globalThis.sessionStorage" throws
 	// "'sessionStorage' property from 'Window': Access is denied for this document" rather than returning undefined.
@@ -264,7 +269,7 @@ export function loggerToMonitoringContext<L extends ITelemetryBaseLogger = ITele
 export function mixinMonitoringContext<L extends ITelemetryBaseLogger = ITelemetryLoggerExt>(
 	logger: L,
 	...configs: (IConfigProviderBase | undefined)[]
-) {
+): MonitoringContext<L> {
 	if (loggerIsMonitoringContext<L>(logger)) {
 		throw new Error("Logger is already a monitoring context");
 	}

package/src/error.ts

@@ -0,0 +1,202 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	FluidErrorTypes,
+	IGenericError,
+	IErrorBase,
+	ITelemetryProperties,
+	IUsageError,
+} from "@fluidframework/core-interfaces";
+import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
+
+import {
+	LoggingError,
+	NORMALIZED_ERROR_TYPE,
+	isExternalError,
+	normalizeError,
+	wrapError,
+} from "./errorLogging";
+import { IFluidErrorBase } from "./fluidErrorBase";
+
+/**
+ * Generic wrapper for an unrecognized/uncategorized error object
+ */
+export class GenericError extends LoggingError implements IGenericError, IFluidErrorBase {
+	readonly errorType = FluidErrorTypes.genericError;
+
+	/**
+	 * Create a new GenericError
+	 * @param message - Error message
+	 * @param error - inner error object
+	 * @param props - Telemetry props to include when the error is logged
+	 */
+	// 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) {
+		// Don't try to log the inner error
+		super(message, props, new Set(["error"]));
+	}
+}
+
+/**
+ * Error indicating an API is being used improperly resulting in an invalid operation.
+ */
+export class UsageError extends LoggingError implements IUsageError, IFluidErrorBase {
+	readonly errorType = FluidErrorTypes.usageError;
+
+	constructor(message: string, props?: ITelemetryProperties) {
+		super(message, { ...props, usageError: true });
+	}
+}
+
+/**
+ * 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
+ */
+export class DataCorruptionError extends LoggingError implements IErrorBase, IFluidErrorBase {
+	readonly errorType = FluidErrorTypes.dataCorruptionError;
+	readonly canRetry = false;
+
+	constructor(message: string, props: ITelemetryProperties) {
+		super(message, { ...props, dataProcessingError: 1 });
+	}
+}
+
+/**
+ * Indicates we hit a fatal error while processing incoming data from the Fluid Service.
+ *
+ * @remarks
+ *
+ * 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.
+ */
+export class DataProcessingError extends LoggingError implements IErrorBase, IFluidErrorBase {
+	/**
+	 * {@inheritDoc IFluidErrorBase.errorType}
+	 */
+	public readonly errorType = FluidErrorTypes.dataProcessingError;
+
+	public readonly canRetry = false;
+
+	private constructor(errorMessage: string) {
+		super(errorMessage);
+	}
+
+	/**
+	 * Create a new `DataProcessingError` detected and raised within the Fluid Framework.
+	 */
+	public static create(
+		errorMessage: string,
+		dataProcessingCodepath: string,
+		sequencedMessage?: ISequencedDocumentMessage,
+		props: ITelemetryProperties = {},
+	): IFluidErrorBase {
+		const dataProcessingError = DataProcessingError.wrapIfUnrecognized(
+			errorMessage,
+			dataProcessingCodepath,
+			sequencedMessage,
+		);
+		dataProcessingError.addTelemetryProperties(props);
+
+		return dataProcessingError;
+	}
+
+	/**
+	 * Wrap the given error in a `DataProcessingError`, unless the error is already of a known type
+	 * with the exception of a normalized {@link LoggingError}, which will still be wrapped.
+	 *
+	 * In either case, the error will have some relevant properties added for telemetry.
+	 *
+	 * @remarks
+	 *
+	 * We wrap conditionally since known error types represent well-understood failure modes, and ideally
+	 * one day we will move away from throwing these errors but rather we'll return them.
+	 * But an unrecognized error needs to be classified as `DataProcessingError`.
+	 *
+	 * @param originalError - The error to be converted.
+	 * @param dataProcessingCodepath - Which code-path failed while processing data.
+	 * @param messageLike - Message to include info about via telemetry props.
+	 *
+	 * @returns Either a new `DataProcessingError`, or (if wrapping is deemed unnecessary) the given error.
+	 */
+	public static wrapIfUnrecognized(
+		originalError: unknown,
+		dataProcessingCodepath: string,
+		messageLike?: Partial<
+			Pick<
+				ISequencedDocumentMessage,
+				| "clientId"
+				| "sequenceNumber"
+				| "clientSequenceNumber"
+				| "referenceSequenceNumber"
+				| "minimumSequenceNumber"
+				| "timestamp"
+			>
+		>,
+	): IFluidErrorBase {
+		const props = {
+			dataProcessingError: 1,
+			dataProcessingCodepath,
+			...(messageLike === undefined
+				? undefined
+				: extractSafePropertiesFromMessage(messageLike)),
+		};
+
+		const normalizedError = normalizeError(originalError, { props });
+		// Note that other errors may have the NORMALIZED_ERROR_TYPE errorType,
+		// but if so they are still suitable to be wrapped as DataProcessingError.
+		if (
+			isExternalError(normalizedError) ||
+			normalizedError.errorType === NORMALIZED_ERROR_TYPE
+		) {
+			// Create a new DataProcessingError to wrap this external error
+			const dataProcessingError = wrapError(
+				normalizedError,
+				(message: string) => new DataProcessingError(message),
+			);
+
+			// Copy over the props above and any others added to this error since first being normalized
+			dataProcessingError.addTelemetryProperties(normalizedError.getTelemetryProperties());
+
+			return dataProcessingError;
+		}
+		return normalizedError;
+	}
+}
+
+/**
+ * Extracts specific properties from the provided message that we know are safe to log.
+ *
+ * @param messageLike - Message to include info about via telemetry props.
+ */
+export const extractSafePropertiesFromMessage = (
+	messageLike: Partial<
+		Pick<
+			ISequencedDocumentMessage,
+			| "clientId"
+			| "sequenceNumber"
+			| "clientSequenceNumber"
+			| "referenceSequenceNumber"
+			| "minimumSequenceNumber"
+			| "timestamp"
+		>
+	>,
+): {
+	messageClientId: string | undefined;
+	messageSequenceNumber: number | undefined;
+	messageClientSequenceNumber: number | undefined;
+	messageReferenceSequenceNumber: number | undefined;
+	messageMinimumSequenceNumber: number | undefined;
+	messageTimestamp: number | undefined;
+} => ({
+	messageClientId: messageLike.clientId === null ? "null" : messageLike.clientId,
+	messageSequenceNumber: messageLike.sequenceNumber,
+	messageClientSequenceNumber: messageLike.clientSequenceNumber,
+	messageReferenceSequenceNumber: messageLike.referenceSequenceNumber,
+	messageMinimumSequenceNumber: messageLike.minimumSequenceNumber,
+	messageTimestamp: messageLike.timestamp,
+});

package/src/errorLogging.ts

@@ -5,9 +5,9 @@
 
 import {
 	ILoggingError,
-	ITaggedTelemetryPropertyType,
-	ITelemetryProperties,
-	TelemetryEventPropertyType,
+	ITelemetryBaseProperties,
+	TelemetryBaseEventPropertyType,
+	Tagged,
 } from "@fluidframework/core-interfaces";
 import { v4 as uuid } from "uuid";
 import {
@@ -16,20 +16,27 @@ import {
 	isFluidError,
 	isValidLegacyError,
 } from "./fluidErrorBase";
-import {
-	ITaggedTelemetryPropertyTypeExt,
-	ITelemetryLoggerExt,
-	TelemetryEventPropertyTypeExt,
-} from "./telemetryTypes";
+import { ITelemetryLoggerExt, TelemetryEventPropertyTypeExt } from "./telemetryTypes";
 
-/** @returns true if value is an object but neither null nor an array */
-const isRegularObject = (value: any): boolean => {
+/**
+ * Determines if the provided value is an object but neither null nor an array.
+ */
+const isRegularObject = (value: unknown): boolean => {
 	return value !== null && !Array.isArray(value) && typeof value === "object";
 };
 
-/** Inspect the given error for common "safe" props and return them */
-export function extractLogSafeErrorProperties(error: any, sanitizeStack: boolean) {
-	const removeMessageFromStack = (stack: string, errorName?: string) => {
+/**
+ * Inspect the given error for common "safe" props and return them.
+ */
+export function extractLogSafeErrorProperties(
+	error: unknown,
+	sanitizeStack: boolean,
+): {
+	message: string;
+	errorType?: string | undefined;
+	stack?: string | undefined;
+} {
+	const removeMessageFromStack = (stack: string, errorName?: string): string => {
 		if (!sanitizeStack) {
 			return stack;
 		}
@@ -41,14 +48,17 @@ export function extractLogSafeErrorProperties(error: any, sanitizeStack: boolean
 		return stackFrames.join("\n");
 	};
 
-	const message = typeof error?.message === "string" ? (error.message as string) : String(error);
+	const message =
+		typeof (error as Partial<Error>)?.message === "string"
+			? (error as Error).message
+			: String(error);
 
 	const safeProps: { message: string; errorType?: string; stack?: string } = {
 		message,
 	};
 
 	if (isRegularObject(error)) {
-		const { errorType, stack, name } = error;
+		const { errorType, stack, name } = error as Partial<IFluidErrorBase>;
 
 		if (typeof errorType === "string") {
 			safeProps.errorType = errorType;
@@ -63,12 +73,19 @@ export function extractLogSafeErrorProperties(error: any, sanitizeStack: boolean
 	return safeProps;
 }
 
-/** type guard for ILoggingError interface */
-export const isILoggingError = (x: any): x is ILoggingError =>
-	typeof x?.getTelemetryProperties === "function";
+/**
+ * type guard for ILoggingError interface
+ */
+export const isILoggingError = (x: unknown): x is ILoggingError =>
+	typeof (x as Partial<ILoggingError>)?.getTelemetryProperties === "function";
 
-/** Copy props from source onto target, but do not overwrite an existing prop that matches */
-function copyProps(target: ITelemetryProperties | LoggingError, source: ITelemetryProperties) {
+/**
+ * Copy props from source onto target, but do not overwrite an existing prop that matches
+ */
+function copyProps(
+	target: ITelemetryBaseProperties | LoggingError,
+	source: ITelemetryBaseProperties,
+): void {
 	for (const key of Object.keys(source)) {
 		if (target[key] === undefined) {
 			target[key] = source[key];
@@ -76,16 +93,23 @@ function copyProps(target: ITelemetryProperties | LoggingError, source: ITelemet
 	}
 }
 
-/** Metadata to annotate an error object when annotating or normalizing it */
+/**
+ * Metadata to annotate an error object when annotating or normalizing it
+ */
 export interface IFluidErrorAnnotations {
-	/** Telemetry props to log with the error */
-	props?: ITelemetryProperties;
+	/**
+	 * Telemetry props to log with the error
+	 */
+	props?: ITelemetryBaseProperties;
 }
 
-/** For backwards compatibility with pre-errorInstanceId valid errors */
+/**
+ * For backwards compatibility with pre-errorInstanceId valid errors
+ */
 function patchLegacyError(
 	legacyError: Omit<IFluidErrorBase, "errorInstanceId">,
 ): asserts legacyError is IFluidErrorBase {
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
 	const patchMe: { -readonly [P in "errorInstanceId"]?: IFluidErrorBase[P] } = legacyError as any;
 	if (patchMe.errorInstanceId === undefined) {
 		patchMe.errorInstanceId = uuid();
@@ -180,8 +204,8 @@ export function generateErrorWithStack(): Error {
 
 	try {
 		throw err;
-	} catch (e) {
-		return e as Error;
+	} catch (error) {
+		return error as Error;
 	}
 }
 
@@ -230,12 +254,16 @@ export function wrapError<T extends LoggingError>(
 	return newError;
 }
 
-/** The same as wrapError, but also logs the innerError, including the wrapping error's instance id */
+/**
+ * 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.
+ */
 export function wrapErrorAndLog<T extends LoggingError>(
 	innerError: unknown,
 	newErrorFn: (message: string) => T,
 	logger: ITelemetryLoggerExt,
-) {
+): T {
 	const newError = wrapError(innerError, newErrorFn);
 
 	// This will match innerError.errorInstanceId if present (see wrapError)
@@ -256,11 +284,11 @@ export function wrapErrorAndLog<T extends LoggingError>(
 	return newError;
 }
 
-function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string) {
+function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string): void {
 	// supposedly setting stack on an Error can throw.
 	try {
 		Object.assign(error, { stack });
-	} catch (errorSettingStack) {
+	} catch {
 		error.addTelemetryProperties({ stack2: stack });
 	}
 }
@@ -270,26 +298,26 @@ function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string) {
  * False for any error we created and raised within the FF codebase via LoggingError base class,
  * or wrapped in a well-known error type
  */
-export function isExternalError(e: any): boolean {
+export function isExternalError(error: unknown): boolean {
 	// LoggingErrors are an internal FF error type. However, an external error can be converted
 	// into a LoggingError if it is normalized. In this case we must use the untrustedOrigin flag to
 	// determine whether the original error was infact external.
-	if (LoggingError.typeCheck(e)) {
-		if ((e as NormalizedLoggingError).errorType === NORMALIZED_ERROR_TYPE) {
-			return e.getTelemetryProperties().untrustedOrigin === 1;
+	if (LoggingError.typeCheck(error)) {
+		if ((error as NormalizedLoggingError).errorType === NORMALIZED_ERROR_TYPE) {
+			return error.getTelemetryProperties().untrustedOrigin === 1;
 		}
 		return false;
 	}
-	return !isValidLegacyError(e);
+	return !isValidLegacyError(error);
 }
 
 /**
  * Type guard to identify if a particular telemetry property appears to be a tagged telemetry property
  */
 export function isTaggedTelemetryPropertyValue(
-	x: ITaggedTelemetryPropertyTypeExt | TelemetryEventPropertyTypeExt,
-): x is ITaggedTelemetryPropertyType | ITaggedTelemetryPropertyTypeExt {
-	return typeof (x as any)?.tag === "string";
+	x: Tagged<TelemetryEventPropertyTypeExt> | TelemetryEventPropertyTypeExt,
+): x is Tagged<TelemetryEventPropertyTypeExt> {
+	return typeof (x as Partial<Tagged<unknown>>)?.tag === "string";
 }
 
 /**
@@ -298,7 +326,7 @@ export function isTaggedTelemetryPropertyValue(
  * @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: any, key: string): TelemetryEventPropertyType {
+function filterValidTelemetryProps(x: unknown, key: string): TelemetryBaseEventPropertyType {
 	if (Array.isArray(x) && x.every((val) => isTelemetryEventPropertyValue(val))) {
 		return JSON.stringify(x);
 	}
@@ -311,7 +339,7 @@ function filterValidTelemetryProps(x: any, key: string): TelemetryEventPropertyT
 }
 
 // checking type of x, returns false if x is null
-function isTelemetryEventPropertyValue(x: any): x is TelemetryEventPropertyType {
+function isTelemetryEventPropertyValue(x: unknown): x is TelemetryBaseEventPropertyType {
 	switch (typeof x) {
 		case "string":
 		case "number":
@@ -325,13 +353,15 @@ function isTelemetryEventPropertyValue(x: any): x is TelemetryEventPropertyType
 /**
  * Walk an object's enumerable properties to find those fit for telemetry.
  */
-function getValidTelemetryProps(obj: any, keysToOmit: Set<string>): ITelemetryProperties {
-	const props: ITelemetryProperties = {};
+function getValidTelemetryProps(obj: object, keysToOmit: Set<string>): ITelemetryBaseProperties {
+	const props: ITelemetryBaseProperties = {};
 	for (const key of Object.keys(obj)) {
 		if (keysToOmit.has(key)) {
 			continue;
 		}
-		const val = obj[key];
+		const val = obj[key] as
+			| TelemetryEventPropertyTypeExt
+			| Tagged<TelemetryEventPropertyTypeExt>;
 
 		// ensure only valid props get logged, since props of logging error could be in any shape
 		if (isTaggedTelemetryPropertyValue(val)) {
@@ -353,9 +383,11 @@ function getValidTelemetryProps(obj: any, keysToOmit: Set<string>): ITelemetryPr
  * 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)
  */
-export const getCircularReplacer = () => {
+// TODO: Use `unknown` instead (API breaking change)
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export const getCircularReplacer = (): ((key: string, value: unknown) => any) => {
 	const seen = new WeakSet();
-	return (key: string, value: any): any => {
+	return (key: string, value: unknown): any => {
 		if (typeof value === "object" && value !== null) {
 			if (seen.has(value)) {
 				return "<removed/circular>";
@@ -365,6 +397,7 @@ export const getCircularReplacer = () => {
 		return value;
 	};
 };
+/* eslint-enable @typescript-eslint/no-explicit-any */
 
 /**
  * Base class for "trusted" errors we create, whose properties can generally be logged to telemetry safely.
@@ -378,15 +411,18 @@ export class LoggingError
 	implements ILoggingError, Omit<IFluidErrorBase, "errorType">
 {
 	private _errorInstanceId = uuid();
-	get errorInstanceId() {
+	get errorInstanceId(): string {
 		return this._errorInstanceId;
 	}
-	overwriteErrorInstanceId(id: string) {
+	overwriteErrorInstanceId(id: string): void {
 		this._errorInstanceId = id;
 	}
 
-	/** Back-compat to appease isFluidError typeguard in old code that may handle this error */
+	/**
+	 * Backwards compatibility to appease {@link isFluidError} in old code that may handle this error.
+	 */
 	// @ts-expect-error - This field shouldn't be referenced in the current version, but needs to exist at runtime.
+	// eslint-disable-next-line @typescript-eslint/prefer-as-const
 	private readonly fluidErrorCode: "-" = "-";
 
 	/**
@@ -397,7 +433,7 @@ export class LoggingError
 	 */
 	constructor(
 		message: string,
-		props?: ITelemetryProperties,
+		props?: ITelemetryBaseProperties,
 		private readonly omitPropsFromLogging: Set<string> = new Set(),
 	) {
 		super(message);
@@ -430,14 +466,14 @@ export class LoggingError
 	/**
 	 * Add additional properties to be logged
 	 */
-	public addTelemetryProperties(props: ITelemetryProperties) {
+	public addTelemetryProperties(props: ITelemetryBaseProperties): void {
 		copyProps(this, props);
 	}
 
 	/**
 	 * Get all properties fit to be logged to telemetry for this error
 	 */
-	public getTelemetryProperties(): ITelemetryProperties {
+	public getTelemetryProperties(): ITelemetryBaseProperties {
 		const taggableProps = getValidTelemetryProps(this, this.omitPropsFromLogging);
 		// Include non-enumerable props that are not returned by getValidTelemetryProps
 		return {
@@ -449,7 +485,9 @@ export class LoggingError
 	}
 }
 
-/** The Error class used when normalizing an external error */
+/**
+ * The Error class used when normalizing an external error
+ */
 export const NORMALIZED_ERROR_TYPE = "genericError";
 class NormalizedLoggingError extends LoggingError {
 	// errorType "genericError" is used as a default value throughout the code.

package/src/eventEmitterWithErrorHandling.ts

@@ -2,8 +2,8 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { IEvent } from "@fluidframework/common-definitions";
-import { TypedEventEmitter, EventEmitterEventType } from "@fluidframework/common-utils";
+import { TypedEventEmitter, EventEmitterEventType } from "@fluid-internal/client-utils";
+import { IEvent } from "@fluidframework/core-interfaces";
 
 /**
  * Event Emitter helper class
@@ -14,12 +14,14 @@ export class EventEmitterWithErrorHandling<
 	TEvent extends IEvent = IEvent,
 > extends TypedEventEmitter<TEvent> {
 	constructor(
+		// TODO: use `unknown` instead (breaking API change)
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		private readonly errorHandler: (eventName: EventEmitterEventType, error: any) => void,
 	) {
 		super();
 	}
 
-	public emit(event: EventEmitterEventType, ...args: any[]): boolean {
+	public emit(event: EventEmitterEventType, ...args: unknown[]): boolean {
 		try {
 			return super.emit(event, ...args);
 		} catch (error) {

package/src/events.ts

@@ -13,8 +13,8 @@ export function safeRaiseEvent(
 	emitter: EventEmitter,
 	logger: ITelemetryLoggerExt,
 	event: string,
-	...args
-) {
+	...args: unknown[]
+): void {
 	try {
 		emitter.emit(event, ...args);
 	} catch (error) {
@@ -36,7 +36,7 @@ export function raiseConnectedEvent(
 	connected: boolean,
 	clientId?: string,
 	disconnectedReason?: string,
-) {
+): void {
 	try {
 		if (connected) {
 			emitter.emit(connectedEventName, clientId);