@fluidframework/telemetry-utils 2.1.0-274160 → 2.1.0-276985

package/src/sampledTelemetryHelper.ts

@@ -5,7 +5,9 @@
 
 import { performance } from "@fluid-internal/client-utils";
 import type { IDisposable, ITelemetryBaseProperties } from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils/internal";
 
+import { roundToDecimalPlaces } from "./mathTools.js";
 import type {
 	ITelemetryGenericEventExt,
 	ITelemetryLoggerExt,
@@ -44,20 +46,96 @@ interface Measurements {
 	 * Max duration across all the executions since the last event was generated.
 	 */
 	maxDuration?: number;
+
+	/**
+	 * Average duration across all the executions since the last event was generated.
+	 */
+	averageDuration?: number;
+}
+
+/**
+ * The data that will be logged in the telemetry event.
+ */
+interface LoggerData {
+	measurements: Measurements;
+
+	/**
+	 * The sum of the custom data passed into the logger for each key.
+	 * Absence of a given key should be interpreted as 0.
+	 */
+	dataSums: Record<string, number>;
+
+	/**
+	 * The max of the custom data passed into the logger for each key.
+	 */
+	dataMaxes: Record<string, number>;
 }
 
+/**
+ * Helper type for an object whose properties are all numbers
+ *
+ * @internal
+ */
+export type CustomMetrics<TKey> = {
+	[K in keyof TKey]: K extends string ? number : never;
+};
+
+/**
+ * Potentially part of the structure of the return value of the function provided to {@link SampledTelemetryHelper.measure}.
+ *
+ * @see {@link MeasureReturnType} for more details on how this type is used.
+ *
+ * @internal
+ */
+export interface ICustomData<T> {
+	customData: CustomMetrics<T>;
+}
+
+/**
+ * Encapsulates the type-level logic for {@link SampledTelemetryHelper.measure}, to determine the expected return type
+ * for the function that method receives (and by extension, its own return type). In words: {@link SampledTelemetryHelper}
+ * is optionally provided with two generic types: one for custom metrics, and one for the actual return value of the
+ * code that will be measured.
+ *
+ * - If no generic type is provided for custom metrics, then this type is simply the generic type provided for the actual
+ * return value of the measured code (which could be void!).
+ * - If a generic type is provided for custom metrics, then this type has a `customData` property whose type matches that
+ * generic. Then if the generic type for the actual return value is not void, this type also has a property `returnValue`
+ * whose type matches the generic type for the actual return value; if the generic type for the actual return value is
+ * void, then this type _forbids_ a `returnValue` property (technically, it can exist but must be undefined in that case),
+ * to try to ensure that the caller doesn't accidentally provide a function that actually returns a value.
+ *
+ * @internal
+ */
+export type MeasureReturnType<TMeasureReturn, TCustomMetrics> = TCustomMetrics extends void
+	? TMeasureReturn
+	: ICustomData<TCustomMetrics> &
+			(TMeasureReturn extends void
+				? { [K in "returnValue"]?: never }
+				: { returnValue: TMeasureReturn });
+
 /**
  * Helper class that executes a specified code block and writes an
  * {@link @fluidframework/core-interfaces#ITelemetryPerformanceEvent} to a specified logger every time a specified
  * number of executions is reached (or when the class is disposed).
  *
- * The `duration` field in the telemetry event is the duration of the latest execution (sample) of the specified
- * function. See the documentation of the `includeAggregateMetrics` parameter for additional details that can be
- * included.
+ * @remarks
+ * The `duration` field in the telemetry event this class generates is the duration of the latest execution (sample)
+ * of the specified code block.
+ * See the documentation of the `includeAggregateMetrics` parameter for additional details that can be included.
+ *
+ * @typeParam TMeasurementReturn - The return type (in a vacuum) of the code block that will be measured, ignoring
+ * any custom metric data that might be required by this class. E.g., the code might just return a boolean.
+ * @typeParam TCustomMetrics - A type that contains the custom properties that will be used by an instance of this class
+ * for custom metrics. Each property in this type should be a number.
  *
  * @internal
  */
-export class SampledTelemetryHelper implements IDisposable {
+export class SampledTelemetryHelper<
+	TMeasureReturn = void,
+	TCustomMetrics extends CustomMetrics<TCustomMetrics> = void,
+> implements IDisposable
+{
 	private _disposed: boolean = false;
 
 	/**
@@ -67,7 +145,7 @@ export class SampledTelemetryHelper implements IDisposable {
 		return this._disposed;
 	}
 
-	private readonly measurementsMap = new Map<string, Measurements>();
+	private readonly measurementsMap = new Map<string, LoggerData>();
 
 	/**
 	 * @param eventBase -
@@ -97,7 +175,12 @@ export class SampledTelemetryHelper implements IDisposable {
 
 	/**
 	 * Executes the specified code and keeps track of execution time statistics.
-	 * If it's been called enough times (the sampleThreshold for the class) then it generates a log message with the necessary information.
+	 * When it's been called enough times (the sampleThreshold for the class) then it generates a log message with the
+	 * necessary information.
+	 *
+	 * @remarks It's the responsibility of the caller to ensure that the same same set of custom metric properties is
+	 * provided each time this method is called on a given instance of {@link SampledTelemetryHelper}.
+	 * Otherwise the final measurements in the telemetry event may not be accurate.
 	 *
 	 * @param codeToMeasure - The code to be executed and measured.
 	 * @param bucket - A key to track executions of the code block separately.
@@ -105,16 +188,25 @@ export class SampledTelemetryHelper implements IDisposable {
 	 * If no such distinction needs to be made, do not provide a value.
 	 * @returns Whatever the passed-in code block returns.
 	 */
-	public measure<T>(codeToMeasure: () => T, bucket: string = ""): T {
+	public measure(
+		codeToMeasure: () => MeasureReturnType<TMeasureReturn, TCustomMetrics>,
+		bucket: string = "",
+	): MeasureReturnType<TMeasureReturn, TCustomMetrics> {
 		const start = performance.now();
 		const returnValue = codeToMeasure();
 		const duration = performance.now() - start;
 
-		let m = this.measurementsMap.get(bucket);
-		if (m === undefined) {
-			m = { count: 0, duration: -1 };
-			this.measurementsMap.set(bucket, m);
+		let loggerData = this.measurementsMap.get(bucket);
+		if (loggerData === undefined) {
+			loggerData = {
+				measurements: { count: 0, duration: -1 },
+				dataSums: {},
+				dataMaxes: {},
+			};
+			this.measurementsMap.set(bucket, loggerData);
 		}
+
+		const m = loggerData.measurements;
 		m.count++;
 		m.duration = duration;
 
@@ -124,19 +216,77 @@ export class SampledTelemetryHelper implements IDisposable {
 			m.maxDuration = Math.max(m.maxDuration ?? 0, duration);
 		}
 
+		if (this.isCustomData(returnValue)) {
+			loggerData = this.accumulateCustomData(returnValue.customData, loggerData);
+		}
+
 		if (m.count >= this.sampleThreshold) {
+			// Computed separately to avoid multiple division operations.
+			if (this.includeAggregateMetrics) {
+				m.averageDuration = (m.totalDuration ?? 0) / m.count;
+			}
 			this.flushBucket(bucket);
 		}
 
 		return returnValue;
 	}
 
+	private isCustomData(data: unknown): data is ICustomData<TCustomMetrics> {
+		return (
+			typeof data === "object" &&
+			data !== null &&
+			"customData" in data &&
+			typeof data.customData === "object"
+		);
+	}
+
+	private accumulateCustomData(
+		customData: CustomMetrics<TCustomMetrics>,
+		loggerData: LoggerData,
+	): LoggerData {
+		for (const [key, val] of Object.entries(customData)) {
+			assert(typeof key === "string", "Key should be a string");
+			assert(typeof val === "number", "Value should be a number");
+
+			loggerData.dataSums[key] = (loggerData.dataSums[key] ?? 0) + val;
+			loggerData.dataMaxes[key] = Math.max(
+				loggerData.dataMaxes[key] ?? Number.NEGATIVE_INFINITY,
+				val,
+			);
+		}
+
+		return loggerData;
+	}
+
+	private processCustomData(loggerData: LoggerData, count: number): Record<string, number> {
+		const processedCustomData: Record<string, number> = {};
+
+		if (loggerData.dataSums === undefined || loggerData.dataMaxes === undefined) {
+			return processedCustomData;
+		}
+
+		const dataSums = loggerData.dataSums;
+		const dataMaxes = loggerData.dataMaxes;
+
+		for (const [key, val] of Object.entries(dataSums)) {
+			// implementation of class guarantees the keys between dataMaxes and dataSums align.
+			processedCustomData[`avg_${key}`] = roundToDecimalPlaces(val / count, 6);
+			processedCustomData[`max_${key}`] = dataMaxes[key] ?? 0;
+		}
+
+		return processedCustomData;
+	}
+
 	private flushBucket(bucket: string): void {
-		const measurements = this.measurementsMap.get(bucket);
-		if (measurements === undefined) {
+		const loggerData = this.measurementsMap.get(bucket);
+		if (loggerData === undefined) {
 			return;
 		}
 
+		const measurements = loggerData.measurements;
+
+		const processedCustomData = this.processCustomData(loggerData, measurements.count);
+
 		if (measurements.count !== 0) {
 			const bucketProperties = this.perBucketProperties.get(bucket);
 
@@ -144,6 +294,7 @@ export class SampledTelemetryHelper implements IDisposable {
 				...this.eventBase,
 				...bucketProperties, // If the bucket doesn't exist and this is undefined, things work as expected
 				...measurements,
+				...processedCustomData,
 			};
 
 			this.logger.sendPerformanceEvent(telemetryEvent);

package/src/telemetryTypes.ts

@@ -13,6 +13,7 @@ import type { ITelemetryBaseLogger, LogLevel, Tagged } from "@fluidframework/cor
  * error - Error log event, ideally 0 of these are logged during a session
  *
  * performance - Includes duration, and often has _start, _end, or _cancel suffixes for activity tracking
+ * @legacy
  * @alpha
  */
 export type TelemetryEventCategory = "generic" | "error" | "performance";
@@ -23,6 +24,7 @@ export type TelemetryEventCategory = "generic" | "error" | "performance";
  * @remarks
  * Includes extra types beyond {@link @fluidframework/core-interfaces#TelemetryBaseEventPropertyType}, which must be
  * converted before sending to a base logger.
+ * @legacy
  * @alpha
  */
 export type TelemetryEventPropertyTypeExt =
@@ -48,6 +50,7 @@ export interface ITaggedTelemetryPropertyTypeExt {
 
 /**
  * JSON-serializable properties, which will be logged with telemetry.
+ * @legacy
  * @alpha
  */
 export type ITelemetryPropertiesExt = Record<
@@ -78,6 +81,7 @@ export interface ITelemetryEventExt extends ITelemetryPropertiesExt {
 /**
  * Informational (non-error) telemetry event
  * @remarks Maps to category = "generic"
+ * @legacy
  * @alpha
  */
 export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
@@ -96,6 +100,7 @@ export interface ITelemetryGenericEventExt extends ITelemetryPropertiesExt {
 /**
  * Error telemetry event.
  * @remarks Maps to category = "error"
+ * @legacy
  * @alpha
  */
 export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
@@ -108,6 +113,7 @@ export interface ITelemetryErrorEventExt extends ITelemetryPropertiesExt {
 /**
  * Performance telemetry event.
  * @remarks Maps to category = "performance"
+ * @legacy
  * @alpha
  */
 export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt {
@@ -123,6 +129,7 @@ export interface ITelemetryPerformanceEventExt extends ITelemetryGenericEventExt
  * @remarks
  * This interface is meant to be used internally within the Fluid Framework,
  * and `ITelemetryBaseLogger` should be used when loggers are passed between layers.
+ * @legacy
  * @alpha
  */
 export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {