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
+---
+
+All internal implementations of ITelemetryLoggerExt now tag events with no explicit logLevel as essential
+
+`@fluidframework/telemetry-utils` previously forwarded events with no explicit `logLevel` to the base logger as `undefined` (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. If undefined, the event will be sent with {@link LogLevelConst.essential | LogLevel.essential}.
 	 */
 	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

@@ -217,7 +217,7 @@ export abstract class TelemetryLogger implements TelemetryLoggerExt {
 	 *
 	 * @param event - the event to send
 	 */
-	public abstract send(event: ITelemetryBaseEvent, logLevel?: LogLevel): void;
+	public abstract send(event: ITelemetryBaseEvent, logLevel: LogLevel): void;
 
 	/**
 	 * Send a telemetry event with the logger
@@ -230,12 +230,15 @@ 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
+			| typeof LogLevel.essential = LogLevel.essential,
 	): void {
 		this.sendTelemetryEventCore(
 			{ ...event, category: event.category ?? "generic" },
 			error,
-			event.category === "error" ? LogLevel.error : logLevel,
+			event.category === "error" ? LogLevel.essential : logLevel,
 		);
 	}
 
@@ -244,12 +247,12 @@ export abstract class TelemetryLogger implements TelemetryLoggerExt {
 	 *
 	 * @param event - the event to send
 	 * @param error - optional error object to log
-	 * @param logLevel - optional level of the log.
+	 * @param logLevel - level of the log.
 	 */
-	protected sendTelemetryEventCore(
+	private sendTelemetryEventCore(
 		event: ITelemetryGenericEventExt & { category: TelemetryEventCategory },
-		error?: unknown,
-		logLevel?: LogLevel,
+		error: unknown,
+		logLevel: LogLevel,
 	): void {
 		const newEvent = convertToBaseEvent(event);
 		if (error !== undefined) {
@@ -280,7 +283,7 @@ export abstract class TelemetryLogger implements TelemetryLoggerExt {
 				category: "error",
 			},
 			error,
-			LogLevel.error,
+			LogLevel.essential,
 		);
 	}
 
@@ -295,7 +298,10 @@ 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
+			| typeof LogLevel.essential = LogLevel.essential,
 	): void {
 		const perfEvent = {
 			...event,
@@ -305,7 +311,7 @@ export abstract class TelemetryLogger implements TelemetryLoggerExt {
 		this.sendTelemetryEventCore(
 			perfEvent,
 			error,
-			perfEvent.category === "error" ? LogLevel.error : logLevel,
+			perfEvent.category === "error" ? LogLevel.essential : logLevel,
 		);
 	}
 
@@ -517,9 +523,10 @@ export class ChildLogger extends TelemetryLogger {
 		return this.baseLogger.minLogLevel;
 	}
 
-	private shouldFilterOutEvent(event: ITelemetryBaseEvent, logLevel?: LogLevel): boolean {
-		const eventLogLevel = logLevel ?? LogLevel.default;
-		const configLogLevel = this.baseLogger.minLogLevel ?? LogLevel.default;
+	private shouldFilterOutEvent(event: ITelemetryBaseEvent, logLevel: LogLevel): boolean {
+		// Determine the log level of the event. The log level is now required, so it will always be provided.
+		const eventLogLevel = logLevel;
+		const configLogLevel = this.baseLogger.minLogLevel ?? LogLevel.info;
 		// Filter out in case event log level is below what is wanted in config.
 		return eventLogLevel < configLogLevel;
 	}
@@ -529,7 +536,7 @@ export class ChildLogger extends TelemetryLogger {
 	 *
 	 * @param event - the event to send
 	 */
-	public send(event: ITelemetryBaseEvent, logLevel?: LogLevel): void {
+	public send(event: ITelemetryBaseEvent, logLevel: LogLevel): void {
 		if (this.shouldFilterOutEvent(event, logLevel)) {
 			return;
 		}
@@ -618,7 +625,7 @@ export class MultiSinkLogger extends TelemetryLogger {
 
 		super(namespace, realProperties);
 		this.loggers = loggers;
-		this._minLogLevelOfAllLoggers = LogLevel.default;
+		this._minLogLevelOfAllLoggers = LogLevel.info;
 		this.calculateMinLogLevel();
 	}
 
@@ -630,7 +637,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;
 		}
@@ -653,10 +660,10 @@ export class MultiSinkLogger extends TelemetryLogger {
 	 *
 	 * @param event - the event to send to all the registered logger
 	 */
-	public send(event: ITelemetryBaseEvent): void {
+	public send(event: ITelemetryBaseEvent, logLevel: LogLevel): void {
 		const newEvent = this.prepareEvent(event);
 		for (const logger of this.loggers) {
-			logger.send(newEvent);
+			logger.send(newEvent, logLevel);
 		}
 	}
 }
@@ -693,14 +700,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.essential | LogLevel.essential} 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 +728,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.essential | LogLevel.essential} 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 +742,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 +771,8 @@ 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, the `logLevel` property is left unset and the effective default is determined by
+	 * the logger implementation.
 	 * @returns The results of the executed task
 	 *
 	 * @remarks Note that if the "same" event (category + eventName) would be emitted by different
@@ -775,7 +786,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 +818,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. If undefined, the event will be sent with {@link @fluidframework/core-interfaces#LogLevelConst.essential | LogLevel.essential}.
 	 */
 	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. If undefined, the event will be sent with {@link @fluidframework/core-interfaces#LogLevelConst.essential | LogLevel.essential}.
 	 */
 	sendPerformanceEvent(
 		event: ITelemetryPerformanceEventExt,
 		error?: unknown,
-		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	): void;
 }