@fluidframework/telemetry-utils 2.0.0-rc.4.0.6 → 2.0.0-rc.5.0.0

package/src/errorLogging.ts

@@ -7,12 +7,7 @@ import type { ITelemetryBaseProperties, Tagged } from "@fluidframework/core-inte
 import type { ILoggingError } from "@fluidframework/core-interfaces/internal";
 import { v4 as uuid } from "uuid";
 
-import {
-	IFluidErrorBase,
-	hasErrorInstanceId,
-	isFluidError,
-	isValidLegacyError,
-} from "./fluidErrorBase.js";
+import { type IFluidErrorBase, hasErrorInstanceId, isFluidError } from "./fluidErrorBase.js";
 import { convertToBasePropertyType } from "./logger.js";
 import type {
 	ITelemetryLoggerExt,
@@ -111,19 +106,6 @@ export interface IFluidErrorAnnotations {
 	props?: ITelemetryBaseProperties;
 }
 
-/**
- * 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();
-	}
-}
-
 /**
  * Normalize the given error yielding a valid Fluid Error
  * @returns A valid Fluid Error with any provided annotations applied
@@ -136,11 +118,6 @@ export function normalizeError(
 	error: unknown,
 	annotations: IFluidErrorAnnotations = {},
 ): IFluidErrorBase {
-	// Back-compat, while IFluidErrorBase is rolled out
-	if (isValidLegacyError(error)) {
-		patchLegacyError(error);
-	}
-
 	if (isFluidError(error)) {
 		// We can simply add the telemetry props to the error and return it
 		error.addTelemetryProperties(annotations.props ?? {});
@@ -180,7 +157,12 @@ export function normalizeError(
 
 	const errorTelemetryProps = LoggingError.typeCheck(error)
 		? error.getTelemetryProperties()
-		: { untrustedOrigin: 1 }; // This will let us filter errors that did not originate from our own codebase
+		: {
+				untrustedOrigin: 1, // This will let us filter errors that did not originate from our own codebase
+				// FUTURE: Once 2.0 becomes LTS, switch to this more explicit property name
+				// Consider using a string to distinguish cases like "dependency" v. "callback"
+				// errorRunningExternalCode: 1,
+			};
 
 	fluidError.addTelemetryProperties({
 		...errorTelemetryProps,
@@ -244,7 +226,10 @@ export function wrapError<T extends LoggingError>(
 	innerError: unknown,
 	newErrorFn: (message: string) => T,
 ): T {
-	const { message, stack } = extractLogSafeErrorProperties(innerError, false /* sanitizeStack */);
+	const { message, stack } = extractLogSafeErrorProperties(
+		innerError,
+		false /* sanitizeStack */,
+	);
 
 	const newError = newErrorFn(message);
 
@@ -254,7 +239,12 @@ export function wrapError<T extends LoggingError>(
 
 	// Mark external errors with untrustedOrigin flag
 	if (isExternalError(innerError)) {
-		newError.addTelemetryProperties({ untrustedOrigin: 1 });
+		newError.addTelemetryProperties({
+			untrustedOrigin: 1,
+			// FUTURE: Once 2.0 becomes LTS, switch to this more explicit property name
+			// Consider using a string to distinguish cases like "dependency" v. "callback"
+			// errorRunningExternalCode: 1,
+		});
 	}
 
 	// Reuse errorInstanceId
@@ -266,7 +256,7 @@ export function wrapError<T extends LoggingError>(
 	}
 
 	// Lastly, copy over all other telemetry properties. Note these will not overwrite existing properties
-	// This will include the untrustedOrigin property if the inner error itself was created from an external error
+	// This will include the untrustedOrigin/errorRunningExternalCode info if the inner error itself was created from an external error
 	if (isILoggingError(innerError)) {
 		newError.addTelemetryProperties(innerError.getTelemetryProperties());
 	}
@@ -331,15 +321,18 @@ export function overwriteStack(error: IFluidErrorBase | LoggingError, stack: str
  */
 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.
+	// into a LoggingError if it is normalized. In this case we must use the untrustedOrigin/errorRunningExternalCode flag to
+	// determine whether the original error was in fact external.
 	if (LoggingError.typeCheck(error)) {
 		if ((error as NormalizedLoggingError).errorType === NORMALIZED_ERROR_TYPE) {
-			return error.getTelemetryProperties().untrustedOrigin === 1;
+			const props = error.getTelemetryProperties();
+			// NOTE: errorRunningExternalCode is not currently used - once this "read" code reaches LTS,
+			// we can switch to writing this more explicit property
+			return props.untrustedOrigin === 1 || !!props.errorRunningExternalCode;
 		}
 		return false;
 	}
-	return !isValidLegacyError(error);
+	return true;
 }
 
 /**
@@ -354,6 +347,8 @@ export function isTaggedTelemetryPropertyValue(
 	return typeof (x as Partial<Tagged<unknown>>)?.tag === "string";
 }
 
+// TODO: Use `unknown` instead (API breaking change)
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * Borrowed from
  * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cyclic_object_value#examples}
@@ -363,8 +358,6 @@ export function isTaggedTelemetryPropertyValue(
  *
  * @internal
  */
-// 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: unknown): any => {
@@ -393,27 +386,20 @@ export class LoggingError
 	implements ILoggingError, Omit<IFluidErrorBase, "errorType">
 {
 	private _errorInstanceId = uuid();
-	get errorInstanceId(): string {
+	public get errorInstanceId(): string {
 		return this._errorInstanceId;
 	}
-	overwriteErrorInstanceId(id: string): void {
+	public overwriteErrorInstanceId(id: string): void {
 		this._errorInstanceId = id;
 	}
 
-	/**
-	 * 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: "-" = "-";
-
 	/**
 	 * Create a new LoggingError
 	 * @param message - Error message to use for Error base class
 	 * @param props - telemetry props to include on the error for when it's logged
 	 * @param omitPropsFromLogging - properties by name to omit from telemetry props
 	 */
-	constructor(
+	public constructor(
 		message: string,
 		props?: ITelemetryBaseProperties,
 		private readonly omitPropsFromLogging: Set<string> = new Set(),
@@ -494,9 +480,9 @@ export const NORMALIZED_ERROR_TYPE = "genericError";
 class NormalizedLoggingError extends LoggingError {
 	// errorType "genericError" is used as a default value throughout the code.
 	// Note that this matches ContainerErrorTypes/DriverErrorTypes' genericError
-	errorType = NORMALIZED_ERROR_TYPE;
+	public readonly errorType = NORMALIZED_ERROR_TYPE;
 
-	constructor(errorProps: Pick<IFluidErrorBase, "message" | "stack">) {
+	public constructor(errorProps: Pick<IFluidErrorBase, "message" | "stack">) {
 		super(errorProps.message);
 
 		if (errorProps.stack !== undefined) {

package/src/eventEmitterWithErrorHandling.ts

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { EventEmitterEventType, TypedEventEmitter } from "@fluid-internal/client-utils";
-import { IEvent } from "@fluidframework/core-interfaces";
+import { type EventEmitterEventType, TypedEventEmitter } from "@fluid-internal/client-utils";
+import type { IEvent } from "@fluidframework/core-interfaces";
 
 /**
  * Event Emitter helper class
@@ -20,7 +20,7 @@ import { IEvent } from "@fluidframework/core-interfaces";
 export class EventEmitterWithErrorHandling<
 	TEvent extends IEvent = IEvent,
 > extends TypedEventEmitter<TEvent> {
-	constructor(
+	public 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,

package/src/fluidErrorBase.ts

@@ -96,18 +96,3 @@ export function isFluidError(error: unknown): error is IFluidErrorBase {
 		hasTelemetryPropFunctions(error)
 	);
 }
-
-/**
- * Type guard for old standard of valid/known errors.
- *
- * @internal
- */
-export function isValidLegacyError(
-	error: unknown,
-): error is Omit<IFluidErrorBase, "errorInstanceId"> {
-	return (
-		typeof (error as Partial<IFluidErrorBase>)?.errorType === "string" &&
-		typeof (error as Partial<IFluidErrorBase>)?.message === "string" &&
-		hasTelemetryPropFunctions(error)
-	);
-}

package/src/index.ts

@@ -5,10 +5,10 @@
 
 export {
 	createChildMonitoringContext,
-	MonitoringContext,
+	type MonitoringContext,
 	sessionStorageConfigProvider,
 	mixinMonitoringContext,
-	IConfigProvider,
+	type IConfigProvider,
 	loggerToMonitoringContext,
 	wrapConfigProviderWithDefaults,
 } from "./config.js";
@@ -25,7 +25,7 @@ export {
 	generateErrorWithStack,
 	generateStack,
 	getCircularReplacer,
-	IFluidErrorAnnotations,
+	type IFluidErrorAnnotations,
 	isExternalError,
 	isILoggingError,
 	isTaggedTelemetryPropertyValue,
@@ -43,34 +43,34 @@ export {
 	raiseConnectedEvent,
 	safeRaiseEvent,
 } from "./events.js";
-export {
-	hasErrorInstanceId,
-	IFluidErrorBase,
-	isFluidError,
-	isValidLegacyError,
-} from "./fluidErrorBase.js";
+export { hasErrorInstanceId, type IFluidErrorBase, isFluidError } from "./fluidErrorBase.js";
 export {
 	eventNamespaceSeparator,
 	createChildLogger,
 	createMultiSinkLogger,
 	formatTick,
-	IPerformanceEventMarkers,
-	ITelemetryLoggerPropertyBag,
-	ITelemetryLoggerPropertyBags,
-	MultiSinkLoggerProperties,
+	type IPerformanceEventMarkers,
+	type ITelemetryLoggerPropertyBag,
+	type ITelemetryLoggerPropertyBags,
+	type MultiSinkLoggerProperties,
 	numberFromString,
 	PerformanceEvent,
 	TaggedLoggerAdapter,
 	tagData,
 	tagCodeArtifacts,
 	TelemetryDataTag,
-	TelemetryEventPropertyTypes,
+	type TelemetryEventPropertyTypes,
 } from "./logger.js";
-export { MockLogger } from "./mockLogger.js";
+export { createMockLoggerExt, type IMockLoggerExt, MockLogger } from "./mockLogger.js";
 export { ThresholdCounter } from "./thresholdCounter.js";
 export { SampledTelemetryHelper } from "./sampledTelemetryHelper.js";
-export { createSampledLogger, IEventSampler, ISampledTelemetryLogger } from "./utils.js";
 export {
+	createSampledLogger,
+	type IEventSampler,
+	type ISampledTelemetryLogger,
+	measure,
+} from "./utils.js";
+export type {
 	TelemetryEventPropertyTypeExt,
 	ITelemetryEventExt,
 	ITelemetryGenericEventExt,
@@ -81,3 +81,4 @@ export {
 	ITelemetryPropertiesExt,
 	TelemetryEventCategory,
 } from "./telemetryTypes.js";
+export { TelemetryEventBatcher } from "./telemetryEventBatcher.js";

package/src/logger.ts

@@ -5,11 +5,11 @@
 
 import { performance } from "@fluid-internal/client-utils";
 import {
-	ITelemetryBaseEvent,
-	ITelemetryBaseLogger,
+	type ITelemetryBaseEvent,
+	type ITelemetryBaseLogger,
 	LogLevel,
-	Tagged,
-	TelemetryBaseEventPropertyType,
+	type Tagged,
+	type TelemetryBaseEventPropertyType,
 } from "@fluidframework/core-interfaces";
 
 import {
@@ -23,8 +23,8 @@ import {
 	isILoggingError,
 	isTaggedTelemetryPropertyValue,
 } from "./errorLogging.js";
-import {
-	type ITelemetryErrorEventExt,
+import type {
+	ITelemetryErrorEventExt,
 	ITelemetryEventExt,
 	ITelemetryGenericEventExt,
 	ITelemetryLoggerExt,
@@ -60,9 +60,10 @@ export type TelemetryEventPropertyTypes = ITelemetryPropertiesExt[string];
 /**
  * @alpha
  */
-export interface ITelemetryLoggerPropertyBag {
-	[index: string]: TelemetryEventPropertyTypes | (() => TelemetryEventPropertyTypes);
-}
+export type ITelemetryLoggerPropertyBag = Record<
+	string,
+	TelemetryEventPropertyTypes | (() => TelemetryEventPropertyTypes)
+>;
 
 /**
  * @alpha
@@ -273,10 +274,9 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 		return this.extendProperties(newEvent, includeErrorProps);
 	}
 
-	private extendProperties<T extends ITelemetryLoggerPropertyBag = ITelemetryLoggerPropertyBag>(
-		toExtend: T,
-		includeErrorProps: boolean,
-	): T {
+	private extendProperties<
+		T extends ITelemetryLoggerPropertyBag = ITelemetryLoggerPropertyBag,
+	>(toExtend: T, includeErrorProps: boolean): T {
 		const eventLike: ITelemetryLoggerPropertyBag = toExtend;
 		if (this.properties) {
 			const properties: (undefined | ITelemetryLoggerPropertyBag)[] = [];
@@ -421,8 +421,8 @@ export class ChildLogger extends TelemetryLogger {
 				baseLogger.namespace === undefined
 					? namespace
 					: namespace === undefined
-					? baseLogger.namespace
-					: `${baseLogger.namespace}${TelemetryLogger.eventNamespaceSeparator}${namespace}`;
+						? baseLogger.namespace
+						: `${baseLogger.namespace}${TelemetryLogger.eventNamespaceSeparator}${namespace}`;
 
 			const child = new ChildLogger(
 				baseLogger.baseLogger,
@@ -533,7 +533,7 @@ export class MultiSinkLogger extends TelemetryLogger {
 	 * @param loggers - The list of loggers to use as sinks
 	 * @param tryInheritProperties - Will attempted to copy those loggers properties to this loggers if they are of a known type e.g. one from this package
 	 */
-	constructor(
+	public constructor(
 		namespace?: string,
 		properties?: ITelemetryLoggerPropertyBags,
 		loggers: ITelemetryBaseLogger[] = [],
@@ -855,7 +855,7 @@ export function convertToBasePropertyType(
 		? {
 				value: convertToBasePropertyTypeUntagged(x.value),
 				tag: x.tag,
-		  }
+			}
 		: convertToBasePropertyTypeUntagged(x);
 }
 
@@ -920,11 +920,11 @@ export const tagData = <
 				? () => {
 						value: ReturnType<V[P]>;
 						tag: T;
-				  }
+					}
 				: {
 						value: Exclude<V[P], undefined>;
 						tag: T;
-				  })
+					})
 		| (V[P] extends undefined ? undefined : never);
 } =>
 	// eslint-disable-next-line @typescript-eslint/no-unsafe-return
@@ -982,10 +982,10 @@ export const tagCodeArtifacts = <
 				? () => {
 						value: ReturnType<T[P]>;
 						tag: TelemetryDataTag.CodeArtifact;
-				  }
+					}
 				: {
 						value: Exclude<T[P], undefined>;
 						tag: TelemetryDataTag.CodeArtifact;
-				  })
+					})
 		| (T[P] extends undefined ? undefined : never);
 } => tagData<TelemetryDataTag.CodeArtifact, T>(TelemetryDataTag.CodeArtifact, values);

package/src/mathTools.ts

@@ -0,0 +1,16 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Function to round a number to a specified number of decimal places.
+ *
+ * @param number - The number to round.
+ * @param decimalPlaces - The number of decimal places to round to.
+ * @returns The rounded number.
+ */
+export function roundToDecimalPlaces(number: number, decimalPlaces: number): number {
+	const factor = Math.pow(10, decimalPlaces);
+	return Math.round(number * factor) / factor;
+}