@fluidframework/telemetry-utils 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.225277

package/src/eventEmitterWithErrorHandling.ts

@@ -2,25 +2,37 @@
  * 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
+ *
+ * @remarks
  * Any exceptions thrown by listeners will be caught and raised through "error" event.
  * Any exception thrown by "error" listeners will propagate to the caller.
+ * @privateRemarks
+ * This probably doesn't belong in this package, as it is not telemetry-specific, and is really only intended for internal fluid-framework use.
+ * We should consider moving it to the `core-utils` package.
+ * @public
  */
-export class EventEmitterWithErrorHandling<TEvent extends IEvent = IEvent> extends TypedEventEmitter<TEvent> {
-    constructor(private readonly errorHandler: (eventName: EventEmitterEventType, error: any) => void) {
-        super();
-    }
+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 {
-        try {
-            return super.emit(event, ...args);
-        } catch (error) {
-            this.errorHandler(event, error);
-            return true;
-        }
-    }
+	public emit(event: EventEmitterEventType, ...args: unknown[]): boolean {
+		try {
+			return super.emit(event, ...args);
+		} catch (error) {
+			this.errorHandler(event, error);
+			return true;
+		}
+	}
 }

package/src/events.ts

@@ -3,38 +3,67 @@
  * 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 {
-    ITelemetryLogger,
-} from "@fluidframework/common-definitions";
+import { ITelemetryLoggerExt } from "./telemetryTypes";
 
+/**
+ * Note: The contents of this file really don't belong in this package, as they are only intended for internal use.
+ * They should be moved into the `core-utils` package in the future.
+ */
+
+/**
+ * @internal
+ */
 export const connectedEventName = "connected";
+
+/**
+ * @internal
+ */
 export const disconnectedEventName = "disconnected";
 
+// eslint-disable-next-line jsdoc/require-description
+/**
+ * @internal
+ */
 export function safeRaiseEvent(
-    emitter: EventEmitter,
-    logger: ITelemetryLogger,
-    event: string,
-    ...args) {
-    try {
-        emitter.emit(event, ...args);
-    } catch (error) {
-        logger.sendErrorEvent({ eventName: "RaiseEventError", event }, error);
-    }
+	emitter: EventEmitter,
+	logger: ITelemetryLoggerExt,
+	event: string,
+	...args: unknown[]
+): void {
+	try {
+		emitter.emit(event, ...args);
+	} catch (error) {
+		logger.sendErrorEvent({ eventName: "RaiseEventError", event }, error);
+	}
 }
 
+/**
+ * Raises events pertaining to the connection
+ * @param logger - The logger to log telemetry
+ * @param emitter - The event emitter instance
+ * @param connected - A boolean tracking whether the connection was in a connected state or not
+ * @param clientId - The connected/disconnected clientId
+ * @param disconnectedReason - The reason for the connection to be disconnected (Used for telemetry purposes only)
+ *
+ * @internal
+ */
 export function raiseConnectedEvent(
-    logger: ITelemetryLogger,
-    emitter: EventEmitter,
-    connected: boolean,
-    clientId?: string) {
-    try {
-        if (connected) {
-            emitter.emit(connectedEventName, clientId);
-        } else {
-            emitter.emit(disconnectedEventName);
-        }
-    } catch (error) {
-        logger.sendErrorEvent({ eventName: "RaiseConnectedEventError" }, error);
-    }
+	logger: ITelemetryLoggerExt,
+	emitter: EventEmitter,
+	connected: boolean,
+	clientId?: string,
+	disconnectedReason?: string,
+): void {
+	try {
+		if (connected) {
+			emitter.emit(connectedEventName, clientId);
+		} else {
+			emitter.emit(disconnectedEventName, disconnectedReason);
+		}
+	} catch (error) {
+		logger.sendErrorEvent({ eventName: "RaiseConnectedEventError" }, error);
+	}
 }

package/src/fluidErrorBase.ts

@@ -3,61 +3,109 @@
  * 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.
+ *
+ * @internal
  */
 export interface IFluidErrorBase extends Error {
-    /** Classification of what type of error this is, 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.
-     */
-    readonly message: string;
-
-    /** Error's stack property, made readonly */
-    readonly stack?: string;
-
-    /** Error's name property, made readonly */
-    readonly name: string;
-
-    /**
-     * A Guid identifying this error instance.
-     * Useful in telemetry for deduping 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 */
-    getTelemetryProperties(): ITelemetryProperties;
-    /** Add telemetry properties to this error which will be logged with the error */
-    addTelemetryProperties: (props: ITelemetryProperties) => void;
+	/**
+	 * 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.
+	 *
+	 * @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;
+
+	/**
+	 * See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack}.
+	 */
+	readonly stack?: string;
+
+	/**
+	 * 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.
+	 *
+	 * @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.
+	 */
+	getTelemetryProperties(): ITelemetryProperties;
+
+	/**
+	 * 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.
+ *
+ * @internal
+ */
+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 {
-    return typeof e?.errorType === "string" &&
-        typeof e?.message === "string" &&
-        hasErrorInstanceId(e) &&
-        hasTelemetryPropFunctions(e);
+/**
+ * Type guard for {@link IFluidErrorBase}.
+ *
+ * @internal
+ */
+export function isFluidError(error: unknown): error is IFluidErrorBase {
+	return (
+		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"> {
-    return typeof e?.errorType === "string" &&
-        typeof e?.message === "string" &&
-        hasTelemetryPropFunctions(e);
+/**
+ * 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

@@ -2,22 +2,81 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-export * from "./debugLogger";
-export * from "./errorLogging";
-export * from "./eventEmitterWithErrorHandling";
-export * from "./events";
-export * from "./fluidErrorBase";
-export * from "./logger";
-export * from "./mockLogger";
-export * from "./thresholdCounter";
-export * from "./utils";
-export * from "./sampledTelemetryHelper";
 export {
-    MonitoringContext,
-    IConfigProviderBase,
-    sessionStorageConfigProvider,
-    mixinMonitoringContext,
-    IConfigProvider,
-    ConfigTypes,
-    loggerToMonitoringContext,
+	createChildMonitoringContext,
+	MonitoringContext,
+	sessionStorageConfigProvider,
+	mixinMonitoringContext,
+	IConfigProvider,
+	loggerToMonitoringContext,
 } from "./config";
+export {
+	DataCorruptionError,
+	DataProcessingError,
+	extractSafePropertiesFromMessage,
+	GenericError,
+	UsageError,
+	validatePrecondition,
+} from "./error";
+export {
+	extractLogSafeErrorProperties,
+	generateErrorWithStack,
+	generateStack,
+	getCircularReplacer,
+	IFluidErrorAnnotations,
+	isExternalError,
+	isILoggingError,
+	isTaggedTelemetryPropertyValue,
+	LoggingError,
+	NORMALIZED_ERROR_TYPE,
+	normalizeError,
+	overwriteStack,
+	wrapError,
+	wrapErrorAndLog,
+} from "./errorLogging";
+export { EventEmitterWithErrorHandling } from "./eventEmitterWithErrorHandling";
+export {
+	connectedEventName,
+	disconnectedEventName,
+	raiseConnectedEvent,
+	safeRaiseEvent,
+} from "./events";
+export {
+	hasErrorInstanceId,
+	IFluidErrorBase,
+	isFluidError,
+	isValidLegacyError,
+} from "./fluidErrorBase";
+export {
+	eventNamespaceSeparator,
+	createChildLogger,
+	createMultiSinkLogger,
+	formatTick,
+	IPerformanceEventMarkers,
+	ITelemetryLoggerPropertyBag,
+	ITelemetryLoggerPropertyBags,
+	MultiSinkLoggerProperties,
+	numberFromString,
+	PerformanceEvent,
+	TaggedLoggerAdapter,
+	tagData,
+	tagCodeArtifacts,
+	TelemetryDataTag,
+	TelemetryEventPropertyTypes,
+	TelemetryNullLogger,
+} from "./logger";
+export { MockLogger } from "./mockLogger";
+export { ThresholdCounter } from "./thresholdCounter";
+export { SampledTelemetryHelper } from "./sampledTelemetryHelper";
+export { logIfFalse, createSampledLogger, IEventSampler, ISampledTelemetryLogger } from "./utils";
+export {
+	TelemetryEventPropertyTypeExt,
+	ITelemetryEventExt,
+	ITelemetryGenericEventExt,
+	ITelemetryErrorEventExt,
+	ITelemetryPerformanceEventExt,
+	ITelemetryLoggerExt,
+	ITaggedTelemetryPropertyTypeExt,
+	ITelemetryPropertiesExt,
+	TelemetryEventCategory,
+} from "./telemetryTypes";