feat(telemetry-utils): deprecate LogLevel.default/error and tag unspecified events as essential

.changeset/salty-colts-appear.md

@@ -0,0 +1,15 @@
+---
+"@fluidframework/core-interfaces": minor
+"__section": deprecation
+---
+
+Deprecated LogLevel.default and LogLevel.error
+
+`LogLevel.default` and `LogLevel.error` in `@fluidframework/core-interfaces` are deprecated in favor of the semantically clearer `LogLevel.info` and `LogLevel.essential` respectively.
+
+#### Migration
+
+- `LogLevel.default` (= `20`) → use `LogLevel.info`
+- `LogLevel.error` (= `30`) → use `LogLevel.essential`
+
+Removal is tracked in [issue #26969](https://github.com/microsoft/FluidFramework/issues/26969) and is planned for the v3.0 major release.

.changeset/soft-doors-trade.md

@@ -0,0 +1,20 @@
+---
+"@fluidframework/telemetry-utils": minor
+"__section": other
+---
+
+ChildLogger now tags events with no explicit `logLevel` as `essential`
+
+`@fluidframework/telemetry-utils` previously forwarded events with no explicit `logLevel` to the base logger as `undefined` (effectively treated as `LogLevel.info` = `20`). It now forwards them as `LogLevel.essential` (= `30`). Specifically:
+
+- `ChildLogger.shouldFilterOutEvent` now falls back to `LogLevel.essential` when an event has no `logLevel` (previously fell back to `LogLevel.default` = `LogLevel.info` = `20`).
+- `ChildLogger.send` now forwards `LogLevel.essential` to the base logger when no `logLevel` is supplied, instead of forwarding `undefined`.
+- The implicit `= LogLevel.default` parameter defaults on `TelemetryLogger.sendTelemetryEvent` and `sendPerformanceEvent` were removed; callers that omit `logLevel` now propagate `undefined` through the chain, where `ChildLogger` applies the new `essential` fallback above.
+
+#### Impact for downstream consumers
+
+Internal Fluid events that previously arrived at the base logger with `logLevel = undefined` will now arrive tagged as `30` (`essential`). Hosts that filter telemetry by numeric level should not start dropping `logLevel = 20` events as "non-essential" unless **all** running Fluid versions include this change — older versions still send those same critical events at level `20`, and dropping them would lose telemetry.
+
+#### Events already explicitly tagged as `LogLevel.info`
+
+Note that this change only affects events emitted with **no** explicit `logLevel`. A set of events that are already explicitly tagged with `LogLevel.info` (= `20`) was introduced in [PR #27126](https://github.com/microsoft/FluidFramework/pull/27126) and is unaffected by this change — those events continue to be emitted at level `20` by design and are the intended target for hosts that want to drop non-essential telemetry once all running Fluid versions include both PR #27126 and this change.

packages/common/core-interfaces/api-report/core-interfaces.beta.api.md

@@ -333,7 +333,9 @@ export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
 // @public
 export interface LogLevelConst {
+    // @deprecated
     readonly default: 20;
+    // @deprecated
     readonly error: 30;
     readonly essential: 30;
     readonly info: 20;

packages/common/core-interfaces/api-report/core-interfaces.legacy.alpha.api.md

@@ -478,7 +478,9 @@ export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
 // @public
 export interface LogLevelConst {
+    // @deprecated
     readonly default: 20;
+    // @deprecated
     readonly error: 30;
     readonly essential: 30;
     readonly info: 20;

packages/common/core-interfaces/api-report/core-interfaces.legacy.beta.api.md

@@ -465,7 +465,9 @@ export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
 // @public
 export interface LogLevelConst {
+    // @deprecated
     readonly default: 20;
+    // @deprecated
     readonly error: 30;
     readonly essential: 30;
     readonly info: 20;

packages/common/core-interfaces/api-report/core-interfaces.legacy.public.api.md

@@ -333,7 +333,9 @@ export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
 // @public
 export interface LogLevelConst {
+    // @deprecated
     readonly default: 20;
+    // @deprecated
     readonly error: 30;
     readonly essential: 30;
     readonly info: 20;

packages/common/core-interfaces/api-report/core-interfaces.public.api.md

@@ -333,7 +333,9 @@ export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
 // @public
 export interface LogLevelConst {
+    // @deprecated
     readonly default: 20;
+    // @deprecated
     readonly error: 30;
     readonly essential: 30;
     readonly info: 20;

packages/common/core-interfaces/src/logger.ts

@@ -81,13 +81,15 @@ export interface LogLevelConst {
 
 	/**
 	 * Default LogLevel
-	 * @remarks Prefer {@link LogLevelConst.info | LogLevel.info} when selecting a level explicitly since this will be deprecated and removed in a future release.
+	 * @deprecated Prefer {@link LogLevelConst.info | LogLevel.info} when selecting a level explicitly to preserve prior treatment. Planned to be removed in 3.0.0.
+	 * @see {@link https://github.com/microsoft/FluidFramework/issues/26969 | Issue #26969} for removal tracking.
 	 */
 	readonly default: 20;
 
 	/**
 	 * To log errors.
-	 * @remarks Prefer {@link LogLevelConst.essential | LogLevel.essential} when selecting a level since this will be deprecated and removed in a future release.
+	 * @deprecated Prefer {@link LogLevelConst.essential | LogLevel.essential} when selecting a level. Planned to be removed in 3.0.0.
+	 * @see {@link https://github.com/microsoft/FluidFramework/issues/26969 | Issue #26969} for removal tracking.
 	 */
 	readonly error: 30;
 }
@@ -120,13 +122,13 @@ export interface ITelemetryBaseLogger {
 	/**
 	 * Log a telemetry event, if it meets the appropriate log-level threshold (see {@link ITelemetryBaseLogger.minLogLevel}).
 	 * @param event - The event to log.
-	 * @param logLevel - The log level of the event. Default: {@link LogLevelConst.default | LogLevel.default}.
+	 * @param logLevel - The log level of the event. Default: {@link LogLevelConst.info | LogLevel.info}.
 	 */
 	send(event: ITelemetryBaseEvent, logLevel?: LogLevel): void;
 
 	/**
 	 * Minimum log level to be logged.
-	 * @defaultValue {@link LogLevelConst.default | LogLevel.default}.
+	 * @defaultValue {@link LogLevelConst.info | LogLevel.info}.
 	 */
 	minLogLevel?: LogLevel;
 }

packages/loader/container-loader/src/test/container.spec.ts

@@ -9,7 +9,8 @@ import {
 	TypedEventEmitter,
 	type IProvideLayerCompatDetails,
 } from "@fluid-internal/client-utils";
-import { AttachState, type IAudience } from "@fluidframework/container-definitions";
+import type { IAudience } from "@fluidframework/container-definitions";
+import { AttachState } from "@fluidframework/container-definitions";
 import type {
 	ICriticalContainerError,
 	IContainer,

packages/utils/telemetry-utils/api-report/telemetry-utils.legacy.beta.api.md

@@ -34,9 +34,9 @@ export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
     // @deprecated
     sendErrorEvent(event: ITelemetryErrorEventExt, error?: unknown): void;
     // @deprecated
-    sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.default): void;
+    sendPerformanceEvent(event: ITelemetryPerformanceEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.info): void;
     // @deprecated
-    sendTelemetryEvent(event: ITelemetryGenericEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.default): void;
+    sendTelemetryEvent(event: ITelemetryGenericEventExt, error?: unknown, logLevel?: typeof LogLevel.verbose | typeof LogLevel.info): void;
 }
 
 // @beta @legacy (undocumented)

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

@@ -230,12 +230,12 @@ export abstract class TelemetryLogger implements TelemetryLoggerExt {
 	public sendTelemetryEvent(
 		event: ITelemetryGenericEventExt,
 		error?: unknown,
-		logLevel: typeof LogLevel.verbose | typeof LogLevel.default = LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	): void {
 		this.sendTelemetryEventCore(
 			{ ...event, category: event.category ?? "generic" },
 			error,
-			event.category === "error" ? LogLevel.error : logLevel,
+			event.category === "error" ? LogLevel.essential : logLevel,
 		);
 	}
 
@@ -280,7 +280,7 @@ export abstract class TelemetryLogger implements TelemetryLoggerExt {
 				category: "error",
 			},
 			error,
-			LogLevel.error,
+			LogLevel.essential,
 		);
 	}
 
@@ -295,7 +295,7 @@ export abstract class TelemetryLogger implements TelemetryLoggerExt {
 	public sendPerformanceEvent(
 		event: ITelemetryPerformanceEventExt,
 		error?: unknown,
-		logLevel: typeof LogLevel.verbose | typeof LogLevel.default = LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	): void {
 		const perfEvent = {
 			...event,
@@ -305,7 +305,7 @@ export abstract class TelemetryLogger implements TelemetryLoggerExt {
 		this.sendTelemetryEventCore(
 			perfEvent,
 			error,
-			perfEvent.category === "error" ? LogLevel.error : logLevel,
+			perfEvent.category === "error" ? LogLevel.essential : logLevel,
 		);
 	}
 
@@ -518,8 +518,9 @@ export class ChildLogger extends TelemetryLogger {
 	}
 
 	private shouldFilterOutEvent(event: ITelemetryBaseEvent, logLevel?: LogLevel): boolean {
-		const eventLogLevel = logLevel ?? LogLevel.default;
-		const configLogLevel = this.baseLogger.minLogLevel ?? LogLevel.default;
+		// Determine the log level of the event. If none is provided, default to essential
+		const eventLogLevel = logLevel ?? LogLevel.essential;
+		const configLogLevel = this.baseLogger.minLogLevel ?? LogLevel.info;
 		// Filter out in case event log level is below what is wanted in config.
 		return eventLogLevel < configLogLevel;
 	}
@@ -533,7 +534,8 @@ export class ChildLogger extends TelemetryLogger {
 		if (this.shouldFilterOutEvent(event, logLevel)) {
 			return;
 		}
-		this.baseLogger.send(this.prepareEvent(event), logLevel);
+		// If no log level was provided, default to essential
+		this.baseLogger.send(this.prepareEvent(event), logLevel ?? LogLevel.essential);
 	}
 }
 
@@ -618,7 +620,7 @@ export class MultiSinkLogger extends TelemetryLogger {
 
 		super(namespace, realProperties);
 		this.loggers = loggers;
-		this._minLogLevelOfAllLoggers = LogLevel.default;
+		this._minLogLevelOfAllLoggers = LogLevel.info;
 		this.calculateMinLogLevel();
 	}
 
@@ -630,7 +632,7 @@ export class MultiSinkLogger extends TelemetryLogger {
 		if (this.loggers.length > 0) {
 			const logLevels: LogLevel[] = [];
 			for (const logger of this.loggers) {
-				logLevels.push(logger.minLogLevel ?? LogLevel.default);
+				logLevels.push(logger.minLogLevel ?? LogLevel.info);
 			}
 			this._minLogLevelOfAllLoggers = Math.min(...logLevels) as LogLevel;
 		}
@@ -693,14 +695,15 @@ export class PerformanceEvent {
 	 * @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.
 	 * @param logLevel - optional {@link LogLevel} for events emitted by this performance event.
+	 * If unspecified, {@link @fluidframework/core-interfaces#LogLevelConst.info | LogLevel.info} will be used.
 	 * @returns An instance of {@link PerformanceEvent}
 	 */
 	public static start(
 		logger: TelemetryLoggerExt | ITelemetryLoggerExt,
 		event: ITelemetryGenericEventExt,
 		markers?: IPerformanceEventMarkers,
 		emitLogs: boolean = true,
-		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	): PerformanceEvent {
 		return new PerformanceEvent(
 			extractTelemetryLoggerExt(logger),
@@ -720,6 +723,7 @@ export class PerformanceEvent {
 	 * @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.
 	 * @param logLevel - optional {@link LogLevel} for events emitted by this performance event.
+	 * If unspecified, {@link @fluidframework/core-interfaces#LogLevelConst.info | LogLevel.info} will be used.
 	 * @returns The results of the executed task
 	 *
 	 * @remarks Note that if the "same" event (category + eventName) would be emitted by different
@@ -733,7 +737,7 @@ export class PerformanceEvent {
 		callback: (event: PerformanceEvent) => T,
 		markers?: IPerformanceEventMarkers,
 		sampleThreshold: number = 1,
-		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	): T {
 		const perfEvent = PerformanceEvent.start(
 			logger,
@@ -762,6 +766,7 @@ export class PerformanceEvent {
 	 * @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.
 	 * @param logLevel - optional {@link LogLevel} for events emitted by this performance event.
+	 * If unspecified, {@link @fluidframework/core-interfaces#LogLevelConst.info | LogLevel.info} will be used.
 	 * @returns The results of the executed task
 	 *
 	 * @remarks Note that if the "same" event (category + eventName) would be emitted by different
@@ -775,7 +780,7 @@ export class PerformanceEvent {
 		callback: (event: PerformanceEvent) => Promise<T>,
 		markers?: IPerformanceEventMarkers,
 		sampleThreshold: number = 1,
-		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	): Promise<T> {
 		const perfEvent = PerformanceEvent.start(
 			logger,
@@ -807,7 +812,7 @@ export class PerformanceEvent {
 		event: ITelemetryGenericEventExt,
 		private readonly markers: IPerformanceEventMarkers = { end: true, cancel: "generic" },
 		private readonly emitLogs: boolean = true,
-		private readonly logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+		private readonly logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	) {
 		this.event = { ...event };
 		if (this.markers.start) {

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

@@ -41,7 +41,7 @@ export class MockLogger implements ITelemetryBaseLogger {
 	public readonly minLogLevel: LogLevel;
 
 	public constructor(minLogLevel?: LogLevel) {
-		this.minLogLevel = minLogLevel ?? LogLevel.default;
+		this.minLogLevel = minLogLevel ?? LogLevel.info;
 	}
 
 	/**
@@ -59,7 +59,7 @@ export class MockLogger implements ITelemetryBaseLogger {
 	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseLogger.send}
 	 */
 	public send(event: ITelemetryBaseEvent, logLevel?: LogLevel): void {
-		if ((logLevel ?? LogLevel.default) >= this.minLogLevel) {
+		if ((logLevel ?? LogLevel.info) >= this.minLogLevel) {
 			this._events.push(event);
 		}
 	}

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

@@ -143,7 +143,7 @@ export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
 	sendTelemetryEvent(
 		event: ITelemetryGenericEventExt,
 		error?: unknown,
-		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	): void;
 
 	/**
@@ -166,7 +166,7 @@ export interface ITelemetryLoggerExt extends ITelemetryBaseLogger {
 	sendPerformanceEvent(
 		event: ITelemetryPerformanceEventExt,
 		error?: unknown,
-		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	): void;
 }
 
@@ -183,12 +183,12 @@ export interface TelemetryLoggerExt extends ITelemetryBaseLogger {
 	 * Send an information telemetry event.
 	 * @param event - Event to send.
 	 * @param error - Optional error object to log.
-	 * @param logLevel - Optional level of the log. Default: {@link @fluidframework/core-interfaces#LogLevel.default}.
+	 * @param logLevel - Optional level of the log. Default: {@link @fluidframework/core-interfaces#LogLevelConst.info | LogLevel.info}.
 	 */
 	sendTelemetryEvent(
 		event: ITelemetryGenericEventExt,
 		error?: unknown,
-		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	): void;
 
 	/**
@@ -202,11 +202,11 @@ export interface TelemetryLoggerExt extends ITelemetryBaseLogger {
 	 * Send a performance telemetry event.
 	 * @param event - Event to send
 	 * @param error - Optional error object to log.
-	 * @param logLevel - Optional level of the log. Default: {@link @fluidframework/core-interfaces#LogLevelConst.default | LogLevel.default}.
+	 * @param logLevel - Optional level of the log. Default: {@link @fluidframework/core-interfaces#LogLevelConst.info | LogLevel.info}.
 	 */
 	sendPerformanceEvent(
 		event: ITelemetryPerformanceEventExt,
 		error?: unknown,
-		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	): void;
 }

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

@@ -194,15 +194,15 @@ describe("ChildLogger", () => {
 				sent = true;
 			},
 
-			minLogLevel: LogLevel.error,
+			minLogLevel: LogLevel.essential,
 		};
 		const childLogger1 = createChildLogger({ logger });
 
-		childLogger1.send({ category: "error", eventName: "testEvent" }, LogLevel.error);
+		childLogger1.send({ category: "error", eventName: "testEvent" }, LogLevel.essential);
 		assert(sent, "event should be sent");
 
 		sent = false;
-		childLogger1.send({ category: "generic", eventName: "testEvent" }, LogLevel.default);
+		childLogger1.send({ category: "generic", eventName: "testEvent" }, LogLevel.info);
 		assert(!sent, "event should not be sent");
 	});
 
@@ -257,10 +257,10 @@ describe("ChildLogger", () => {
 				}
 				sent = true;
 			},
-			minLogLevel: LogLevel.default,
+			minLogLevel: LogLevel.info,
 		};
 		const multiSinkLogger = createMultiSinkLogger({
-			loggers: [logger1, new MockLogger(LogLevel.error)],
+			loggers: [logger1, new MockLogger(LogLevel.essential)],
 		});
 		const childLogger1 = createChildLogger({
 			logger: multiSinkLogger,
@@ -269,7 +269,7 @@ describe("ChildLogger", () => {
 		childLogger1.send({ category: "generic", eventName: "testEvent" }, LogLevel.verbose);
 		assert(!sent, "verbose event should not be sent");
 
-		childLogger1.send({ category: "generic", eventName: "testEvent" }, LogLevel.default);
+		childLogger1.send({ category: "generic", eventName: "testEvent" }, LogLevel.info);
 		assert(sent, "default event should be sent");
 	});
 });