@fluidframework/telemetry-utils 2.0.0-dev.5.2.0.169897 → 2.0.0-dev.6.4.0.191258

package/src/errorLogging.ts

@@ -5,10 +5,10 @@
 
 import {
 	ILoggingError,
-	ITaggedTelemetryPropertyType,
-	ITelemetryProperties,
-	TelemetryEventPropertyType,
-} from "@fluidframework/common-definitions";
+	ITelemetryBaseProperties,
+	TelemetryBaseEventPropertyType,
+	Tagged,
+} from "@fluidframework/core-interfaces";
 import { v4 as uuid } from "uuid";
 import {
 	hasErrorInstanceId,
@@ -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,18 @@ export function wrapErrorAndLog<T extends LoggingError>(
 	return newError;
 }
 
-function overwriteStack(error: IFluidErrorBase | LoggingError, stack: string) {
-	// 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 (errorSettingStack) {
+	} catch {
 		error.addTelemetryProperties({ stack2: stack });
 	}
 }
@@ -270,35 +305,35 @@ 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";
 }
 
 /**
  * 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: 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 +346,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 +360,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 +390,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 +404,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 +418,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 +440,7 @@ export class LoggingError
 	 */
 	constructor(
 		message: string,
-		props?: ITelemetryProperties,
+		props?: ITelemetryBaseProperties,
 		private readonly omitPropsFromLogging: Set<string> = new Set(),
 	) {
 		super(message);
@@ -414,7 +457,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) {
@@ -430,14 +473,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 +492,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);

package/src/fluidErrorBase.ts

@@ -3,65 +3,101 @@
  * Licensed under the MIT License.
  */
 
-import { ITelemetryProperties } from "@fluidframework/common-definitions";
+import { ITelemetryProperties } from "@fluidframework/core-interfaces";
 
 /**
+ * An error emitted by the Fluid Framework.
+ *
+ * @remarks
+ *
  * All normalized errors flowing through the Fluid Framework adhere to this readonly interface.
- * It features errorType and errorInstanceId on top of Error's members as readonly,
- * and a getter/setter for telemetry props to be included when the error is logged.
+ *
+ * It features the members of {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error | Error}
+ * made readonly, as well as  {@link IFluidErrorBase.errorType} and {@link IFluidErrorBase.errorInstanceId}.
+ * It also features getters and setters for telemetry props to be included when the error is logged.
  */
 export interface IFluidErrorBase extends Error {
-	/** Classification of what type of error this is, used programmatically by consumers to interpret the error */
+	/**
+	 * Classification of what type of error this is.
+	 *
+	 * @remarks Used programmatically by consumers to interpret the error.
+	 */
 	readonly errorType: string;
 
 	/**
 	 * Error's message property, made readonly.
-	 * Be specific, but also take care when including variable data to consider suitability for aggregation in telemetry
-	 * Also avoid including any data that jeopardizes the user's privacy.  Add a tagged telemetry property instead.
+	 *
+	 * @remarks
+	 *
+	 * Recommendations:
+	 *
+	 * Be specific, but also take care when including variable data to consider suitability for aggregation in telemetry.
+	 * Also avoid including any data that jeopardizes the user's privacy. Add a tagged telemetry property instead.
 	 */
 	readonly message: string;
 
-	/** Error's stack property, made readonly */
+	/**
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack}.
+	 */
 	readonly stack?: string;
 
-	/** Error's name property, made readonly */
+	/**
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/name}.
+	 */
 	readonly name: string;
 
 	/**
 	 * A Guid identifying this error instance.
-	 * Useful in telemetry for deduping multiple logging events arising from the same error,
+	 *
+	 * @remarks
+	 *
+	 * Useful in telemetry for deduplicating multiple logging events arising from the same error,
 	 * or correlating an error with an inner error that caused it, in case of error wrapping.
 	 */
 	readonly errorInstanceId: string;
 
-	/** Get the telemetry properties stashed on this error for logging */
+	/**
+	 * Get the telemetry properties stashed on this error for logging.
+	 */
 	getTelemetryProperties(): ITelemetryProperties;
-	/** Add telemetry properties to this error which will be logged with the error */
+
+	/**
+	 * Add telemetry properties to this error which will be logged with the error
+	 */
 	addTelemetryProperties: (props: ITelemetryProperties) => void;
 }
 
-const hasTelemetryPropFunctions = (x: any): boolean =>
-	typeof x?.getTelemetryProperties === "function" &&
-	typeof x?.addTelemetryProperties === "function";
+const hasTelemetryPropFunctions = (x: unknown): boolean =>
+	typeof (x as Partial<IFluidErrorBase>)?.getTelemetryProperties === "function" &&
+	typeof (x as Partial<IFluidErrorBase>)?.addTelemetryProperties === "function";
 
-export const hasErrorInstanceId = (x: any): x is { errorInstanceId: string } =>
-	typeof x?.errorInstanceId === "string";
+/**
+ * Type guard for error data containing the {@link IFluidErrorBase.errorInstanceId} property.
+ */
+export const hasErrorInstanceId = (x: unknown): x is { errorInstanceId: string } =>
+	typeof (x as Partial<{ errorInstanceId: string }>)?.errorInstanceId === "string";
 
-/** type guard for IFluidErrorBase interface */
-export function isFluidError(e: any): e is IFluidErrorBase {
+/**
+ * Type guard for {@link IFluidErrorBase}.
+ */
+export function isFluidError(error: unknown): error is IFluidErrorBase {
 	return (
-		typeof e?.errorType === "string" &&
-		typeof e?.message === "string" &&
-		hasErrorInstanceId(e) &&
-		hasTelemetryPropFunctions(e)
+		typeof (error as Partial<IFluidErrorBase>)?.errorType === "string" &&
+		typeof (error as Partial<IFluidErrorBase>)?.message === "string" &&
+		hasErrorInstanceId(error) &&
+		hasTelemetryPropFunctions(error)
 	);
 }
 
-/** type guard for old standard of valid/known errors */
-export function isValidLegacyError(e: any): e is Omit<IFluidErrorBase, "errorInstanceId"> {
+/**
+ * Type guard for old standard of valid/known errors.
+ */
+export function isValidLegacyError(
+	error: unknown,
+): error is Omit<IFluidErrorBase, "errorInstanceId"> {
 	return (
-		typeof e?.errorType === "string" &&
-		typeof e?.message === "string" &&
-		hasTelemetryPropFunctions(e)
+		typeof (error as Partial<IFluidErrorBase>)?.errorType === "string" &&
+		typeof (error as Partial<IFluidErrorBase>)?.message === "string" &&
+		hasTelemetryPropFunctions(error)
 	);
 }

package/src/index.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 export {
+	createChildMonitoringContext,
 	MonitoringContext,
 	IConfigProviderBase,
 	sessionStorageConfigProvider,
@@ -11,7 +12,13 @@ export {
 	ConfigTypes,
 	loggerToMonitoringContext,
 } from "./config";
-export { DebugLogger } from "./debugLogger";
+export {
+	DataCorruptionError,
+	DataProcessingError,
+	extractSafePropertiesFromMessage,
+	GenericError,
+	UsageError,
+} from "./error";
 export {
 	extractLogSafeErrorProperties,
 	generateErrorWithStack,
@@ -24,6 +31,7 @@ export {
 	LoggingError,
 	NORMALIZED_ERROR_TYPE,
 	normalizeError,
+	overwriteStack,
 	wrapError,
 	wrapErrorAndLog,
 } from "./errorLogging";
@@ -41,19 +49,21 @@ export {
 	isValidLegacyError,
 } from "./fluidErrorBase";
 export {
-	BaseTelemetryNullLogger,
-	ChildLogger,
+	eventNamespaceSeparator,
+	createChildLogger,
+	createMultiSinkLogger,
+	formatTick,
 	IPerformanceEventMarkers,
 	ITelemetryLoggerPropertyBag,
 	ITelemetryLoggerPropertyBags,
-	MultiSinkLogger,
+	numberFromString,
 	PerformanceEvent,
 	TaggedLoggerAdapter,
+	tagData,
+	tagCodeArtifacts,
 	TelemetryDataTag,
 	TelemetryEventPropertyTypes,
-	TelemetryLogger,
 	TelemetryNullLogger,
-	TelemetryUTLogger,
 } from "./logger";
 export { MockLogger } from "./mockLogger";
 export { ThresholdCounter } from "./thresholdCounter";
@@ -68,4 +78,5 @@ export {
 	ITelemetryLoggerExt,
 	ITaggedTelemetryPropertyTypeExt,
 	ITelemetryPropertiesExt,
+	TelemetryEventCategory,
 } from "./telemetryTypes";