@fluidframework/telemetry-utils 2.0.0-internal.5.3.4 → 2.0.0-internal.5.4.2

package/src/logger.ts

@@ -59,14 +59,39 @@ export interface ITelemetryLoggerPropertyBags {
 	error?: ITelemetryLoggerPropertyBag;
 }
 
+/**
+ * Attempts to parse number from string.
+ * If fails,returns original string.
+ * Used to make telemetry data typed (and support math operations, like comparison),
+ * in places where we do expect numbers (like contentsize/duration property in http header)
+ */
+export function numberFromString(str: string | null | undefined): string | number | undefined {
+	if (str === undefined || str === null) {
+		return undefined;
+	}
+	const num = Number(str);
+	return Number.isNaN(num) ? str : num;
+}
+
+export function formatTick(tick: number): number {
+	return Math.floor(tick);
+}
+
+export const eventNamespaceSeparator = ":" as const;
+
 /**
  * TelemetryLogger class contains various helper telemetry methods,
  * encoding in one place schemas for various types of Fluid telemetry events.
  * Creates sub-logger that appends properties to all events
+ *
+ * @deprecated - In a subsequent release this type will no longer be exported, use ITelemetryLogger instead
  */
 export abstract class TelemetryLogger implements ITelemetryLoggerExt {
-	public static readonly eventNamespaceSeparator = ":";
+	public static readonly eventNamespaceSeparator = eventNamespaceSeparator;
 
+	/**
+	 * @deprecated - use formatTick
+	 */
 	public static formatTick(tick: number): number {
 		return Math.floor(tick);
 	}
@@ -76,6 +101,7 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 	 * If fails,returns original string.
 	 * Used to make telemetry data typed (and support math operations, like comparison),
 	 * in places where we do expect numbers (like contentsize/duration property in http header)
+	 * @deprecated - use numberFromString
 	 */
 	public static numberFromString(str: string | null | undefined): string | number | undefined {
 		if (str === undefined || str === null) {
@@ -163,7 +189,7 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 
 		// Will include Nan & Infinity, but probably we do not care
 		if (typeof newEvent.duration === "number") {
-			newEvent.duration = TelemetryLogger.formatTick(newEvent.duration);
+			newEvent.duration = formatTick(newEvent.duration);
 		}
 
 		this.send(newEvent);
@@ -211,6 +237,14 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 		if (this.namespace !== undefined) {
 			newEvent.eventName = `${this.namespace}${TelemetryLogger.eventNamespaceSeparator}${newEvent.eventName}`;
 		}
+		return this.extendProperties(newEvent, includeErrorProps);
+	}
+
+	private extendProperties<T extends ITelemetryLoggerPropertyBag = ITelemetryLoggerPropertyBag>(
+		toExtend: T,
+		includeErrorProps: boolean,
+	) {
+		const eventLike: ITelemetryLoggerPropertyBag = toExtend;
 		if (this.properties) {
 			const properties: (undefined | ITelemetryLoggerPropertyBag)[] = [];
 			properties.push(this.properties.all);
@@ -220,7 +254,7 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 			for (const props of properties) {
 				if (props !== undefined) {
 					for (const key of Object.keys(props)) {
-						if (event[key] !== undefined) {
+						if (eventLike[key] !== undefined) {
 							continue;
 						}
 						const getterOrValue = props[key];
@@ -228,13 +262,13 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 						const value =
 							typeof getterOrValue === "function" ? getterOrValue() : getterOrValue;
 						if (value !== undefined) {
-							newEvent[key] = value;
+							eventLike[key] = value;
 						}
 					}
 				}
 			}
 		}
-		return newEvent;
+		return toExtend;
 	}
 }
 
@@ -284,10 +318,29 @@ export class TaggedLoggerAdapter implements ITelemetryBaseLogger {
 	}
 }
 
+/**
+ * Create a child logger based on the provided props object
+ * @param props - logger is the base logger the child will log to after it's processing, namespace will be prefixed to all event names, properties are default properties that will be applied events.
+ *
+ * @remarks
+ * Passing in no props object (i.e. undefined) will return a logger that is effectively a no-op.
+ */
+export function createChildLogger(props?: {
+	logger?: ITelemetryBaseLogger;
+	namespace?: string;
+	properties?: ITelemetryLoggerPropertyBags;
+}): ITelemetryLoggerExt {
+	if (props === undefined) {
+		return new TelemetryNullLogger();
+	}
+	return ChildLogger.create(props?.logger, props?.namespace, props?.properties);
+}
+
 /**
  * ChildLogger class contains various helper telemetry methods,
  * encoding in one place schemas for various types of Fluid telemetry events.
  * Creates sub-logger that appends properties to all events
+ * @deprecated - Use createChildLogger instead
  */
 export class ChildLogger extends TelemetryLogger {
 	/**
@@ -363,20 +416,60 @@ export class ChildLogger extends TelemetryLogger {
 	}
 }
 
+/**
+ * Create a logger which logs to multiple other loggers based on the provided props object
+ * @param props - loggers are the base loggers that will logged to after it's processing, namespace will be prefixed to all event names, properties are default properties that will be applied events.
+ * tryInheritProperties will attempted to copy those loggers properties to this loggers if they are of a known type e.g. one from this package
+ */
+export function createMultiSinkLogger(props: {
+	namespace?: string;
+	properties?: ITelemetryLoggerPropertyBags;
+	loggers?: (ITelemetryBaseLogger | undefined)[];
+	tryInheritProperties?: true;
+}): ITelemetryLoggerExt {
+	return new MultiSinkLogger(
+		props.namespace,
+		props.properties,
+		props.loggers?.filter((l): l is ITelemetryBaseLogger => l !== undefined),
+		props.tryInheritProperties,
+	);
+}
+
 /**
  * Multi-sink logger
  * Takes multiple ITelemetryBaseLogger objects (sinks) and logs all events into each sink
+ * @deprecated - use createMultiSinkLogger instead
  */
 export class MultiSinkLogger extends TelemetryLogger {
-	protected loggers: ITelemetryBaseLogger[] = [];
-
+	protected loggers: ITelemetryBaseLogger[];
 	/**
 	 * Create multiple sink logger (i.e. logger that sends events to multiple sinks)
 	 * @param namespace - Telemetry event name prefix to add to all events
 	 * @param properties - Base properties to add to all events
+	 * @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(namespace?: string, properties?: ITelemetryLoggerPropertyBags) {
-		super(namespace, properties);
+	constructor(
+		namespace?: string,
+		properties?: ITelemetryLoggerPropertyBags,
+		loggers: ITelemetryBaseLogger[] = [],
+		tryInheritProperties?: true,
+	) {
+		let realProperties = properties !== undefined ? { ...properties } : undefined;
+		if (tryInheritProperties === true) {
+			const merge = (realProperties ??= {});
+			loggers
+				.filter((l): l is this => l instanceof TelemetryLogger)
+				.map((l) => l.properties ?? {})
+				.forEach((cv) => {
+					Object.keys(cv).forEach((k) => {
+						merge[k] = { ...cv[k], ...merge?.[k] };
+					});
+				});
+		}
+
+		super(namespace, realProperties);
+		this.loggers = loggers;
 	}
 
 	/**
@@ -561,6 +654,7 @@ export class PerformanceEvent {
 /**
  * Logger that is useful for UT
  * It can be used in places where logger instance is required, but events should be not send over.
+ * @deprecated - Use createChildLogger instead
  */
 export class TelemetryUTLogger implements ITelemetryLoggerExt {
 	public send(event: ITelemetryBaseEvent): void {}
@@ -596,6 +690,7 @@ export class TelemetryUTLogger implements ITelemetryLoggerExt {
 /**
  * Null logger
  * It can be used in places where logger instance is required, but events should be not send over.
+ * @deprecated - for internal use only
  */
 export class BaseTelemetryNullLogger implements ITelemetryBaseLogger {
 	/**
@@ -611,6 +706,7 @@ export class BaseTelemetryNullLogger implements ITelemetryBaseLogger {
 /**
  * Null logger
  * It can be used in places where logger instance is required, but events should be not send over.
+ * @deprecated - for internal use only
  */
 export class TelemetryNullLogger implements ITelemetryLoggerExt {
 	public send(event: ITelemetryBaseEvent): void {}
@@ -676,3 +772,25 @@ function convertToBasePropertyTypeUntagged(
 			return `INVALID PROPERTY (typed as ${typeof x})`;
 	}
 }
+
+export const tagData = <
+	T extends TelemetryDataTag,
+	V extends Record<string, TelemetryEventPropertyTypeExt>,
+>(
+	tag: T,
+	values: V,
+) =>
+	(Object.entries(values) as [keyof V, V[keyof V]][])
+		.filter((e): e is [keyof V, Exclude<V[keyof V], undefined>] => e[1] !== undefined)
+		.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] };
+			return pv;
+		}, {} as any);
+
+export const tagCodeArtifacts = <T extends Record<string, TelemetryEventPropertyTypeExt>>(
+	values: T,
+) => tagData(TelemetryDataTag.CodeArtifact, values);

package/src/mockLogger.ts

@@ -6,7 +6,7 @@
 import { ITelemetryBaseEvent } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/common-utils";
 import { TelemetryLogger } from "./logger";
-import { ITelemetryLoggerExt } from "./telemetryTypes";
+import { ITelemetryLoggerExt, ITelemetryPropertiesExt } from "./telemetryTypes";
 
 /**
  * The MockLogger records events sent to it, and then can walk back over those events
@@ -185,7 +185,6 @@ ${JSON.stringify(actualEvents)}`);
 		inlineDetailsProp: boolean,
 	): boolean {
 		const { details, ...actualForMatching } = actual;
-		let detailsExpanded = { details };
 		// "details" is used in a lot of telemetry logs to group a bunch of properties together and stringify them.
 		// Some of the properties in the expected event may be inside "details". So, if inlineDetailsProp is true,
 		// extract the properties from "details" in the actual event and inline them in the actual event.
@@ -194,10 +193,35 @@ ${JSON.stringify(actualEvents)}`);
 				typeof details === "string",
 				0x6c9 /* Details should a JSON stringified string if inlineDetailsProp is true */,
 			);
-			detailsExpanded = JSON.parse(details);
+			const detailsExpanded = JSON.parse(details);
+			return matchObjects({ ...actualForMatching, ...detailsExpanded }, expected);
 		}
-		const actualExpanded: ITelemetryBaseEvent = { ...actualForMatching, ...detailsExpanded };
-		const masked = { ...actualExpanded, ...expected };
-		return JSON.stringify(masked) === JSON.stringify(actualExpanded);
+		return matchObjects(actual, expected);
 	}
 }
+
+function matchObjects(actual: ITelemetryPropertiesExt, expected: ITelemetryPropertiesExt) {
+	for (const [expectedKey, expectedValue] of Object.entries(expected)) {
+		const actualValue = actual[expectedKey];
+		if (
+			!Array.isArray(expectedValue) &&
+			expectedValue !== null &&
+			typeof expectedValue === "object"
+		) {
+			if (
+				Array.isArray(actualValue) ||
+				actualValue === null ||
+				typeof actualValue !== "object" ||
+				!matchObjects(
+					actualValue as ITelemetryPropertiesExt,
+					expectedValue as ITelemetryPropertiesExt,
+				)
+			) {
+				return false;
+			}
+		} else if (JSON.stringify(actualValue) !== JSON.stringify(expectedValue)) {
+			return false;
+		}
+	}
+	return true;
+}