feat(telemetry-utils): escalate selected performance events to essential

packages/utils/telemetry-utils/src/logger.ts

@@ -675,7 +675,15 @@ export class MultiSinkLogger extends TelemetryLogger {
 export interface IPerformanceEventMarkers {
 	start?: true;
 	end?: true;
-	cancel?: "generic" | "error"; // tells wether to issue "generic" or "error" category cancel event
+	cancel?: "generic" | "error"; // tells whether to issue "generic" or "error" category cancel event
+	/**
+	 * If specified, _end events whose duration is greater than this threshold are logged as essential.
+	 */
+	endEventEssentialDurationThresholdMs?: number;
+	/**
+	 * If specified, _cancel events are logged as essential while preserving the configured cancel category.
+	 */
+	logCancelAsEssential?: true;
 }
 
 /**
@@ -895,7 +903,27 @@ export class PerformanceEvent {
 			event.duration = this.duration;
 		}
 
-		this.logger.sendPerformanceEvent(event, error, this.logLevel);
+		this.logger.sendPerformanceEvent(event, error, this.getLogLevel(eventNameSuffix, event));
+	}
+
+	private getLogLevel(
+		eventNameSuffix: string,
+		event: ITelemetryPerformanceEventExt,
+	): typeof LogLevel.verbose | typeof LogLevel.info | undefined {
+		if (eventNameSuffix === "cancel" && this.markers.logCancelAsEssential === true) {
+			return undefined;
+		}
+
+		if (
+			eventNameSuffix === "end" &&
+			event.duration !== undefined &&
+			this.markers.endEventEssentialDurationThresholdMs !== undefined &&
+			event.duration > this.markers.endEventEssentialDurationThresholdMs
+		) {
+			return undefined;
+		}
+
+		return this.logLevel;
 	}
 
 	private static readonly eventHits = new Map<string, number>();

packages/utils/telemetry-utils/src/test/performanceEvent.spec.ts

@@ -5,25 +5,29 @@
 
 import { strict as assert } from "node:assert";
 
-import type { ITelemetryBaseEvent } from "@fluidframework/core-interfaces";
+import { LogLevel, type ITelemetryBaseEvent } from "@fluidframework/core-interfaces";
 
 import { PerformanceEvent, TelemetryLogger } from "../logger.js";
 import type { TelemetryLoggerExt } from "../telemetryTypes.js";
 
 class MockLogger extends TelemetryLogger implements TelemetryLoggerExt {
 	public errorsLogged: number = 0;
 	public eventsLogged: number = 0;
+	public readonly events: ITelemetryBaseEvent[] = [];
+	public readonly logLevels: (LogLevel | undefined)[] = [];
 
 	public constructor() {
 		super();
 	}
 
-	public send(event: ITelemetryBaseEvent): void {
+	public send(event: ITelemetryBaseEvent, logLevel?: LogLevel): void {
 		if (event.category === "error") {
 			++this.errorsLogged;
 		}
 
 		++this.eventsLogged;
+		this.events.push(event);
+		this.logLevels.push(logLevel);
 	}
 }
 
@@ -34,6 +38,10 @@ describe("PerformanceEvent", () => {
 	const callback = (): void => {
 		callbackCalls++;
 	};
+	const delay = async (): Promise<void> =>
+		new Promise<void>((resolve) => {
+			setTimeout(resolve, 1);
+		});
 	const asyncCallback = async (event: PerformanceEvent): Promise<string | void> => {
 		const outerPromise = new Promise<string>((resolve, reject) => {
 			Promise.resolve("A")
@@ -95,6 +103,100 @@ describe("PerformanceEvent", () => {
 		);
 	});
 
+	describe("Log level escalation", () => {
+		it("Logs below-threshold end events at the configured log level", () => {
+			const perfEvent = PerformanceEvent.start(
+				logger,
+				{ eventName: "BelowThreshold" },
+				{
+					end: true,
+					endEventEssentialDurationThresholdMs: Number.MAX_SAFE_INTEGER,
+				},
+				true,
+				LogLevel.info,
+			);
+
+			perfEvent.end();
+
+			assert.deepStrictEqual(logger.logLevels, [LogLevel.info]);
+			assert.equal(logger.events[0]?.eventName, "BelowThreshold_end");
+		});
+
+		it("Logs above-threshold end events as essential", async () => {
+			const perfEvent = PerformanceEvent.start(
+				logger,
+				{ eventName: "AboveThreshold" },
+				{
+					end: true,
+					endEventEssentialDurationThresholdMs: 0,
+				},
+				true,
+				LogLevel.info,
+			);
+
+			await delay();
+			perfEvent.end();
+
+			assert.deepStrictEqual(logger.logLevels, [LogLevel.essential]);
+			assert.equal(logger.events[0]?.eventName, "AboveThreshold_end");
+		});
+
+		it("Logs cancel events as essential when configured", () => {
+			const perfEvent = PerformanceEvent.start(
+				logger,
+				{ eventName: "EssentialCancel" },
+				{
+					cancel: "generic",
+					logCancelAsEssential: true,
+				},
+				true,
+				LogLevel.info,
+			);
+
+			perfEvent.cancel();
+
+			assert.deepStrictEqual(logger.logLevels, [LogLevel.essential]);
+			assert.equal(logger.events[0]?.eventName, "EssentialCancel_cancel");
+			assert.equal(logger.events[0]?.category, "generic");
+		});
+
+		it("Preserves scalar LogLevel.info behavior when marker escalation is not configured", () => {
+			const perfEvent = PerformanceEvent.start(
+				logger,
+				{ eventName: "InfoCancel" },
+				{
+					cancel: "generic",
+				},
+				true,
+				LogLevel.info,
+			);
+
+			perfEvent.cancel();
+
+			assert.deepStrictEqual(logger.logLevels, [LogLevel.info]);
+			assert.equal(logger.events[0]?.eventName, "InfoCancel_cancel");
+		});
+
+		it("Continues to log error-category performance events as essential", () => {
+			const perfEvent = PerformanceEvent.start(
+				logger,
+				{ eventName: "ErrorCategory", category: "error" },
+				{
+					end: true,
+					endEventEssentialDurationThresholdMs: Number.MAX_SAFE_INTEGER,
+				},
+				true,
+				LogLevel.info,
+			);
+
+			perfEvent.end();
+
+			assert.deepStrictEqual(logger.logLevels, [LogLevel.essential]);
+			assert.equal(logger.events[0]?.eventName, "ErrorCategory_end");
+			assert.equal(logger.events[0]?.category, "error");
+		});
+	});
+
 	describe("Event sampling", () => {
 		it("Events are logged at least once", async () => {
 			await PerformanceEvent.timedExecAsync(