@fluidframework/telemetry-utils 2.0.0-internal.6.4.0 → 2.0.0-internal.7.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/telemetry-utils",
-  "version": "2.0.0-internal.6.4.0",
+  "version": "2.0.0-internal.7.1.0",
   "description": "Collection of telemetry relates utilities for Fluid",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -39,22 +39,22 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": ">=2.0.0-internal.6.4.0 <2.0.0-internal.6.5.0",
-    "@fluidframework/core-interfaces": ">=2.0.0-internal.6.4.0 <2.0.0-internal.6.5.0",
-    "@fluidframework/core-utils": ">=2.0.0-internal.6.4.0 <2.0.0-internal.6.5.0",
-    "@fluidframework/protocol-definitions": "^1.1.0",
+    "@fluid-internal/client-utils": ">=2.0.0-internal.7.1.0 <2.0.0-internal.7.2.0",
+    "@fluidframework/core-interfaces": ">=2.0.0-internal.7.1.0 <2.0.0-internal.7.2.0",
+    "@fluidframework/core-utils": ">=2.0.0-internal.7.1.0 <2.0.0-internal.7.2.0",
+    "@fluidframework/protocol-definitions": "^3.0.0",
     "debug": "^4.1.1",
     "events": "^3.1.0",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
-    "@fluid-tools/build-cli": "^0.22.0",
-    "@fluidframework/build-common": "^2.0.0",
-    "@fluidframework/build-tools": "^0.22.0",
-    "@fluidframework/eslint-config-fluid": "^2.1.0",
-    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.6.4.0 <2.0.0-internal.6.5.0",
-    "@fluidframework/telemetry-utils-previous": "npm:@fluidframework/telemetry-utils@2.0.0-internal.6.3.0",
-    "@microsoft/api-extractor": "^7.34.4",
+    "@fluid-tools/build-cli": "^0.25.0",
+    "@fluidframework/build-common": "^2.0.1",
+    "@fluidframework/build-tools": "^0.25.0",
+    "@fluidframework/eslint-config-fluid": "^3.0.0",
+    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.7.1.0 <2.0.0-internal.7.2.0",
+    "@fluidframework/telemetry-utils-previous": "npm:@fluidframework/telemetry-utils@2.0.0-internal.7.0.0",
+    "@microsoft/api-extractor": "^7.37.0",
     "@types/debug": "^4.1.5",
     "@types/events": "^3.0.0",
     "@types/mocha": "^9.1.1",
@@ -63,15 +63,15 @@
     "c8": "^7.7.1",
     "copyfiles": "^2.4.1",
     "cross-env": "^7.0.3",
-    "eslint": "~8.6.0",
+    "eslint": "~8.50.0",
     "mocha": "^10.2.0",
     "mocha-json-output-reporter": "^2.0.1",
     "mocha-multi-reporters": "^1.5.1",
     "moment": "^2.21.0",
-    "prettier": "~2.6.2",
+    "prettier": "~3.0.3",
     "rimraf": "^4.4.0",
     "sinon": "^7.4.2",
-    "typescript": "~4.5.5"
+    "typescript": "~5.1.6"
   },
   "typeValidation": {
     "broken": {}
@@ -80,11 +80,11 @@
     "build": "fluid-build . --task build",
     "build:commonjs": "fluid-build . --task commonjs",
     "build:compile": "fluid-build . --task compile",
-    "build:docs": "api-extractor run --local --typescript-compiler-folder ../../../node_modules/typescript && copyfiles -u 1 ./_api-extractor-temp/doc-models/* ../../../_api-extractor-temp/",
+    "build:docs": "api-extractor run --local",
     "build:esnext": "tsc --project ./tsconfig.esnext.json",
     "build:test": "tsc --project ./src/test/tsconfig.json",
     "bump-version": "npm version minor --no-push --no-git-tag-version && npm run build:genver",
-    "ci:build:docs": "api-extractor run --typescript-compiler-folder ../../../node_modules/typescript && copyfiles -u 1 ./_api-extractor-temp/* ../../../_api-extractor-temp/",
+    "ci:build:docs": "api-extractor run",
     "clean": "rimraf --glob 'dist' 'lib' '*.tsbuildinfo' '*.build.log' '_api-extractor-temp' 'nyc'",
     "eslint": "eslint --format stylish src",
     "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",

package/src/error.ts

@@ -35,9 +35,13 @@ export class GenericError extends LoggingError implements IGenericError, IFluidE
 	 * @param error - inner error object
 	 * @param props - Telemetry props to include when the error is logged
 	 */
-	// TODO: Use `unknown` instead (API breaking change because error is not just an input parameter, but a public member of the class)
-	// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
-	constructor(message: string, public readonly error?: any, props?: ITelemetryBaseProperties) {
+	constructor(
+		message: string,
+		// TODO: Use `unknown` instead (API breaking change because error is not just an input parameter, but a public member of the class)
+		// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+		public readonly error?: any,
+		props?: ITelemetryBaseProperties,
+	) {
 		// Don't try to log the inner error
 		super(message, props, new Set(["error"]));
 	}

package/src/index.ts

@@ -68,7 +68,7 @@ export {
 export { MockLogger } from "./mockLogger";
 export { ThresholdCounter } from "./thresholdCounter";
 export { SampledTelemetryHelper } from "./sampledTelemetryHelper";
-export { logIfFalse } from "./utils";
+export { logIfFalse, createSampledLogger, IEventSampler, ISampledTelemetryLogger } from "./utils";
 export {
 	TelemetryEventPropertyTypeExt,
 	ITelemetryEventExt,

package/src/logger.ts

@@ -566,22 +566,55 @@ export interface IPerformanceEventMarkers {
  * Helper class to log performance events
  */
 export class PerformanceEvent {
+	/**
+	 * Creates an instance of {@link PerformanceEvent} and starts measurements
+	 * @param logger - the logger to be used for publishing events
+	 * @param event - the logging event details which will be published with the performance measurements
+	 * @param markers - See {@link IPerformanceEventMarkers}
+	 * @param recordHeapSize - whether or not to also record memory performance
+	 * @param emitLogs - should this instance emit logs. If set to false, logs will not be emitted to the logger,
+	 * but measurements will still be performed and any specified markers will be generated.
+	 * @returns An instance of {@link PerformanceEvent}
+	 */
 	public static start(
 		logger: ITelemetryLoggerExt,
 		event: ITelemetryGenericEvent,
 		markers?: IPerformanceEventMarkers,
 		recordHeapSize: boolean = false,
+		emitLogs: boolean = true,
 	): PerformanceEvent {
-		return new PerformanceEvent(logger, event, markers, recordHeapSize);
+		return new PerformanceEvent(logger, event, markers, recordHeapSize, emitLogs);
 	}
 
+	/**
+	 * Measure a synchronous task
+	 * @param logger - the logger to be used for publishing events
+	 * @param event - the logging event details which will be published with the performance measurements
+	 * @param callback - the task to be executed and measured
+	 * @param markers - See {@link IPerformanceEventMarkers}
+	 * @param sampleThreshold - events with the same name and category will be sent to the logger
+	 * only when we hit this many executions of the task. If unspecified, all events will be sent.
+	 * @returns The results of the executed task
+	 *
+	 * @remarks Note that if the "same" event (category + eventName) would be emitted by different
+	 * tasks (`callback`), `sampleThreshold` is still applied only based on the event's category + eventName,
+	 * so executing either of the tasks will increase the internal counter and they
+	 * effectively "share" the sampling rate for the event.
+	 */
 	public static timedExec<T>(
 		logger: ITelemetryLoggerExt,
 		event: ITelemetryGenericEvent,
 		callback: (event: PerformanceEvent) => T,
 		markers?: IPerformanceEventMarkers,
+		sampleThreshold: number = 1,
 	): T {
-		const perfEvent = PerformanceEvent.start(logger, event, markers);
+		const perfEvent = PerformanceEvent.start(
+			logger,
+			event,
+			markers,
+			undefined, // recordHeapSize
+			PerformanceEvent.shouldReport(event, sampleThreshold),
+		);
 		try {
 			const ret = callback(perfEvent);
 			perfEvent.autoEnd();
@@ -592,14 +625,37 @@ export class PerformanceEvent {
 		}
 	}
 
+	/**
+	 * Measure an asynchronous task
+	 * @param logger - the logger to be used for publishing events
+	 * @param event - the logging event details which will be published with the performance measurements
+	 * @param callback - the task to be executed and measured
+	 * @param markers - See {@link IPerformanceEventMarkers}
+	 * @param recordHeapSize - whether or not to also record memory performance
+	 * @param sampleThreshold - events with the same name and category will be sent to the logger
+	 * only when we hit this many executions of the task. If unspecified, all events will be sent.
+	 * @returns The results of the executed task
+	 *
+	 * @remarks Note that if the "same" event (category + eventName) would be emitted by different
+	 * tasks (`callback`), `sampleThreshold` is still applied only based on the event's category + eventName,
+	 * so executing either of the tasks will increase the internal counter and they
+	 * effectively "share" the sampling rate for the event.
+	 */
 	public static async timedExecAsync<T>(
 		logger: ITelemetryLoggerExt,
 		event: ITelemetryGenericEvent,
 		callback: (event: PerformanceEvent) => Promise<T>,
 		markers?: IPerformanceEventMarkers,
 		recordHeapSize?: boolean,
+		sampleThreshold: number = 1,
 	): Promise<T> {
-		const perfEvent = PerformanceEvent.start(logger, event, markers, recordHeapSize);
+		const perfEvent = PerformanceEvent.start(
+			logger,
+			event,
+			markers,
+			recordHeapSize,
+			PerformanceEvent.shouldReport(event, sampleThreshold),
+		);
 		try {
 			const ret = await callback(perfEvent);
 			perfEvent.autoEnd();
@@ -624,6 +680,7 @@ export class PerformanceEvent {
 		event: ITelemetryGenericEvent,
 		private readonly markers: IPerformanceEventMarkers = { end: true, cancel: "generic" },
 		private readonly recordHeapSize: boolean = false,
+		private readonly emitLogs: boolean = true,
 	) {
 		this.event = { ...event };
 		if (this.markers.start) {
@@ -686,6 +743,10 @@ export class PerformanceEvent {
 			return;
 		}
 
+		if (!this.emitLogs) {
+			return;
+		}
+
 		const event: ITelemetryPerformanceEvent = { ...this.event, ...props };
 		event.eventName = `${event.eventName}_${eventNameSuffix}`;
 		if (eventNameSuffix !== "start") {
@@ -701,13 +762,20 @@ export class PerformanceEvent {
 				}
 			}
 		} else if (this.recordHeapSize) {
-			this.startMemoryCollection = (
-				performance as PerformanceWithMemory
-			)?.memory?.usedJSHeapSize;
+			this.startMemoryCollection = (performance as PerformanceWithMemory)?.memory
+				?.usedJSHeapSize;
 		}
 
 		this.logger.sendPerformanceEvent(event, error);
 	}
+
+	private static readonly eventHits = new Map<string, number>();
+	private static shouldReport(event: ITelemetryGenericEvent, sampleThreshold: number): boolean {
+		const eventKey = `.${event.category}.${event.eventName}`;
+		const hitCount = PerformanceEvent.eventHits.get(eventKey) ?? 0;
+		PerformanceEvent.eventHits.set(eventKey, hitCount >= sampleThreshold ? 1 : hitCount + 1);
+		return hitCount % sampleThreshold === 0;
+	}
 }
 
 /**

package/src/utils.ts

@@ -7,6 +7,8 @@ import {
 	ITelemetryBaseLogger,
 	ITelemetryGenericEvent,
 } from "@fluidframework/core-interfaces";
+import { loggerToMonitoringContext } from "./config";
+import { ITelemetryGenericEventExt, ITelemetryLoggerExt } from "./telemetryTypes";
 
 /**
  * Like assert, but logs only if the condition is false, rather than throwing
@@ -30,3 +32,86 @@ export function logIfFalse(
 	logger.send(newEvent);
 	return false;
 }
+
+/**
+ * An object that contains a callback used in conjunction with the {@link createSampledLogger} utility function to provide custom logic for sampling events.
+ *
+ * @internal
+ */
+export interface IEventSampler {
+	/**
+	 * @returns true if the event should be sampled or false if not
+	 */
+	sample: () => boolean | undefined;
+}
+
+/**
+ * A telemetry logger that has sampling capabilities
+ *
+ * @internal
+ */
+export interface ISampledTelemetryLogger extends ITelemetryLoggerExt {
+	/**
+	 * Indicates if the feature flag to disable sampling is set.
+	 *
+	 * @remarks Exposed to enable some advanced scenarios where the code using the sampled logger
+	 * could take advantage of skipping the execution of some logic when it can determine
+	 * it won't be necessary because the telemetry event that needs it wouldn't be
+	 * emitted anyway.
+	 */
+	isSamplingDisabled: boolean;
+}
+
+/**
+ * Wraps around an existing logger matching the {@link ITelemetryLoggerExt} interface and provides the ability to only log a subset of events using a sampling strategy provided by an ${@link IEventSampler}.
+ * You can chose to not provide an event sampler which is effectively a no-op, meaning that it will be treated as if the sampler always returns true.
+ *
+ * @remarks
+ * The sampling functionality uses the Fluid telemetry logging configuration along with the optionally provided event sampling callback to determine whether an event should
+ * be logged or not.
+ *
+ * Configuration object parameters:
+ * 'Fluid.Telemetry.DisableSampling': if this config value is set to true, all events will be unsampled and therefore logged.
+ * Otherwise only a sample will be logged according to the provided event sampler callback.
+ *
+ * Note that the same sampler is used for all APIs of the returned logger. If you want separate events flowing through the returned logger to be sampled separately, the {@link IEventSampler} you provide should track them separately.
+ *
+ * @internal
+ */
+export function createSampledLogger(
+	logger: ITelemetryLoggerExt,
+	eventSampler?: IEventSampler,
+): ISampledTelemetryLogger {
+	const monitoringContext = loggerToMonitoringContext(logger);
+	const isSamplingDisabled =
+		monitoringContext.config.getBoolean("Fluid.Telemetry.DisableSampling") ?? false;
+
+	const sampledLogger = {
+		send: (event: ITelemetryBaseEvent): void => {
+			// The sampler uses the following logic for sending events:
+			// 1. If isSamplingDisabled is true, then this means events should be unsampled. Therefore we send the event without any checks.
+			// 2. If isSamplingDisabled is false, then event should be sampled using the event sampler, if the sampler is not defined just send all events, other use the eventSampler.sample() method.
+			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				logger.send(event);
+			}
+		},
+		sendTelemetryEvent: (event: ITelemetryGenericEventExt): void => {
+			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				logger.sendTelemetryEvent(event);
+			}
+		},
+		sendErrorEvent: (event: ITelemetryGenericEventExt): void => {
+			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				logger.sendErrorEvent(event);
+			}
+		},
+		sendPerformanceEvent: (event: ITelemetryGenericEventExt): void => {
+			if (isSamplingDisabled || eventSampler === undefined || eventSampler.sample()) {
+				logger.sendPerformanceEvent(event);
+			}
+		},
+		isSamplingDisabled,
+	};
+
+	return sampledLogger;
+}