feat(core-interfaces): Add info and essential log levels to LogLevel

.changeset/tender-poems-float.md

@@ -0,0 +1,22 @@
+---
+"@fluidframework/core-interfaces": minor
+"@fluidframework/telemetry-utils": minor
+"__section": deprecation
+---
+Deprecated default and error in LogLevel
+
+Two new `LogLevel` members have been added to `@fluidframework/core-interfaces` to better express intent:
+
+- `LogLevel.info` — replaces `LogLevel.default` (same numeric value). Use this for informational session logs that could be omitted at high telemetry volumes.
+- `LogLevel.essential` — replaces `LogLevel.error` (same numeric value). Use this for critical operational events that should always be collected.
+
+`LogLevel.default` and `LogLevel.error` are now `@deprecated` and will be removed in a future release (see [issue #26969](https://github.com/microsoft/FluidFramework/issues/26969) for the removal timeline).
+
+If an event does not have a log level specified, it should be treated as if it were `LogLevel.essential`.
+
+**Migration:**
+
+| Deprecated | Replacement |
+|---|---|
+| `LogLevel.default` | `LogLevel.info` |
+| `LogLevel.error` | `LogLevel.essential` |

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

@@ -321,6 +321,8 @@ export type Listeners<T extends object> = {
 // @public
 export const LogLevel: {
     readonly verbose: 10;
+    readonly info: 20;
+    readonly essential: 30;
     readonly default: 20;
     readonly error: 30;
 };

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

@@ -473,6 +473,8 @@ export type Listeners<T extends object> = {
 // @public
 export const LogLevel: {
     readonly verbose: 10;
+    readonly info: 20;
+    readonly essential: 30;
     readonly default: 20;
     readonly error: 30;
 };

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

@@ -424,6 +424,8 @@ export type Listeners<T extends object> = {
 // @public
 export const LogLevel: {
     readonly verbose: 10;
+    readonly info: 20;
+    readonly essential: 30;
     readonly default: 20;
     readonly error: 30;
 };

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

@@ -321,6 +321,8 @@ export type Listeners<T extends object> = {
 // @public
 export const LogLevel: {
     readonly verbose: 10;
+    readonly info: 20;
+    readonly essential: 30;
     readonly default: 20;
     readonly error: 30;
 };

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

@@ -321,6 +321,8 @@ export type Listeners<T extends object> = {
 // @public
 export const LogLevel: {
     readonly verbose: 10;
+    readonly info: 20;
+    readonly essential: 30;
     readonly default: 20;
     readonly error: 30;
 };

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

@@ -55,8 +55,36 @@ export interface ITelemetryBaseEvent extends ITelemetryBaseProperties {
  * @public
  */
 export const LogLevel = {
-	verbose: 10, // To log any verbose event for example when you are debugging something.
+	/**
+	 * Chatty logs useful for debugging.
+	 * @remarks They need not be collected in production.
+	 */
+	verbose: 10,
+
+	/**
+	 * Information about the session.
+	 * @remarks These logs could be omitted in some sessions if needed (e.g. to reduce overall telemetry volume).
+	 * If any are collected from a particular session, all should be.
+	 */
+	info: 20,
+
+	/**
+	 * Essential information about the operation of Fluid.
+	 * @remarks  It is recommended that these should always be collected, even in production, for diagnostic purposes.
+	 * If an event does not have a log level specified, it should be treated as if it were LogLevel.essential.
+	 */
+	essential: 30,
+
+	/**
+	 * @deprecated Use {@link (LogLevel:variable).info}. If an event does not have a log level specified, it should be treated as if it were LogLevel.essential.
+	 * See {@link https://github.com/microsoft/FluidFramework/issues/26969} for removal timeline.
+	 */
 	default: 20, // Default log level
+
+	/**
+	 * @deprecated Use {@link (LogLevel:variable).essential}.
+	 * See {@link https://github.com/microsoft/FluidFramework/issues/26969} for removal timeline.
+	 */
 	error: 30, // To log errors.
 } as const;
 

packages/service-clients/end-to-end-tests/azure-client/src/test/multiprocess/childClient.tool.ts

@@ -14,8 +14,7 @@ import {
 } from "@fluidframework/azure-client";
 import { AttachState } from "@fluidframework/container-definitions";
 import { ConnectionState } from "@fluidframework/container-loader";
-import type { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
-import { LogLevel } from "@fluidframework/core-interfaces";
+import type { ITelemetryBaseLogger, LogLevel } from "@fluidframework/core-interfaces";
 import type { ScopeType } from "@fluidframework/driver-definitions/legacy";
 import type { ContainerSchema, IFluidContainer } from "@fluidframework/fluid-static";
 import {
@@ -74,7 +73,10 @@ function telemetryEventInterestLevel(eventName: string): "none" | "basic" | "det
 	return "none";
 }
 
-function selectiveVerboseLog(event: ITelemetryBaseEvent, logLevel?: LogLevel): void {
+function selectiveVerboseLog(
+	event: ITelemetryBaseEvent,
+	logLevel: LogLevel | undefined,
+): void {
 	const interest = telemetryEventInterestLevel(event.eventName);
 	if (interest === "none") {
 		return;
@@ -86,7 +88,7 @@ function selectiveVerboseLog(event: ITelemetryBaseEvent, logLevel?: LogLevel): v
 	if (interest === "details") {
 		content.details = event.details;
 	}
-	log(`[${logLevel ?? LogLevel.default}]`, content);
+	log(`[${logLevel ?? "unspecified"}]`, content);
 }
 
 /**

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

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

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

@@ -183,16 +183,18 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 	 * @param error - optional error object to log
 	 * @param logLevel - optional level of the log. It category of event is set as error,
 	 * then the logLevel will be upgraded to be an error.
+	 *
+	 * @remarks The default value for logLevel will be updated to {@link @fluidframework/core-interfaces#LogLevel.essential}.
 	 */
 	public sendTelemetryEvent(
 		event: ITelemetryGenericEventExt,
 		error?: unknown,
-		logLevel: typeof LogLevel.verbose | typeof LogLevel.default = LogLevel.default,
+		logLevel: typeof LogLevel.verbose | typeof LogLevel.info = LogLevel.info,
 	): void {
 		this.sendTelemetryEventCore(
 			{ ...event, category: event.category ?? "generic" },
 			error,
-			event.category === "error" ? LogLevel.error : logLevel,
+			event.category === "error" ? LogLevel.essential : logLevel,
 		);
 	}
 
@@ -237,7 +239,7 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 				category: "error",
 			},
 			error,
-			LogLevel.error,
+			LogLevel.essential,
 		);
 	}
 
@@ -248,11 +250,13 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 	 * @param error - optional error object to log
 	 * @param logLevel - optional level of the log. It category of event is set as error,
 	 * then the logLevel will be upgraded to be an error.
+	 *
+	 * @remarks The default value for logLevel will be updated to {@link @fluidframework/core-interfaces#LogLevel.essential}.
 	 */
 	public sendPerformanceEvent(
 		event: ITelemetryPerformanceEventExt,
 		error?: unknown,
-		logLevel: typeof LogLevel.verbose | typeof LogLevel.default = LogLevel.default,
+		logLevel: typeof LogLevel.verbose | typeof LogLevel.info = LogLevel.info,
 	): void {
 		const perfEvent = {
 			...event,
@@ -262,7 +266,7 @@ export abstract class TelemetryLogger implements ITelemetryLoggerExt {
 		this.sendTelemetryEventCore(
 			perfEvent,
 			error,
-			perfEvent.category === "error" ? LogLevel.error : logLevel,
+			perfEvent.category === "error" ? LogLevel.essential : logLevel,
 		);
 	}
 
@@ -459,8 +463,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;
+		// The default value for eventLogLevel will be updated to {@link @fluidframework/core-interfaces#LogLevel.essential} once issue #26910 is resolved.
+		const eventLogLevel = logLevel ?? LogLevel.info;
+		const configLogLevel = this.baseLogger.minLogLevel ?? LogLevel.info;
 		// Filter out in case event log level is below what is wanted in config.
 		return eventLogLevel < configLogLevel;
 	}
@@ -559,7 +564,7 @@ export class MultiSinkLogger extends TelemetryLogger {
 
 		super(namespace, realProperties);
 		this.loggers = loggers;
-		this._minLogLevelOfAllLoggers = LogLevel.default;
+		this._minLogLevelOfAllLoggers = LogLevel.info;
 		this.calculateMinLogLevel();
 	}
 
@@ -571,7 +576,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;
 		}

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

@@ -41,7 +41,8 @@ export class MockLogger implements ITelemetryBaseLogger {
 	public readonly minLogLevel: LogLevel;
 
 	public constructor(minLogLevel?: LogLevel) {
-		this.minLogLevel = minLogLevel ?? LogLevel.default;
+		//  The default value for logLevel will be updated to {@link @fluidframework/core-interfaces#LogLevel.essential} once issue #26910 is resolved.
+		this.minLogLevel = minLogLevel ?? LogLevel.info;
 	}
 
 	/**
@@ -59,7 +60,8 @@ export class MockLogger implements ITelemetryBaseLogger {
 	 * {@inheritDoc @fluidframework/core-interfaces#ITelemetryBaseLogger.send}
 	 */
 	public send(event: ITelemetryBaseEvent, logLevel?: LogLevel): void {
-		if ((logLevel ?? LogLevel.default) >= this.minLogLevel) {
+		//  The default value for logLevel will be updated to {@link @fluidframework/core-interfaces#LogLevel.essential} once issue #26910 is resolved.
+		if ((logLevel ?? LogLevel.info) >= this.minLogLevel) {
 			this._events.push(event);
 		}
 	}

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

@@ -117,12 +117,14 @@ export interface ITelemetryLoggerExt 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#LogLevel.info}.
+	 *
+	 * @remarks The default value for logLevel will be updated to {@link @fluidframework/core-interfaces#LogLevel.essential} once issue #26910 is resolved.
 	 */
 	sendTelemetryEvent(
 		event: ITelemetryGenericEventExt,
 		error?: unknown,
-		logLevel?: typeof LogLevel.verbose | typeof LogLevel.default,
+		logLevel?: typeof LogLevel.verbose | typeof LogLevel.info,
 	): void;
 
 	/**
@@ -136,11 +138,13 @@ export interface ITelemetryLoggerExt 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#LogLevel.default}.
+	 * @param logLevel - Optional level of the log. Default: {@link @fluidframework/core-interfaces#LogLevel.info}.
+	 *
+	 * @remarks The default value for logLevel will be updated to {@link @fluidframework/core-interfaces#LogLevel.essential} once issue #26910 is resolved.
 	 */
 	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.info)],
 		});
 		const childLogger1 = createChildLogger({
 			logger: multiSinkLogger,
@@ -269,7 +269,10 @@ 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);
-		assert(sent, "verbose event should be sent");
+		childLogger1.send({ category: "generic", eventName: "testEvent" }, LogLevel.info);
+		assert(sent, "info event should be sent");
+
+		childLogger1.send({ category: "generic", eventName: "testEvent" }, LogLevel.essential);
+		assert(sent, "essential event should be sent");
 	});
 });

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

@@ -66,14 +66,14 @@ describe("MultiSinkLogger", () => {
 	});
 
 	it("MultiSink logger set the logLevel to min logLevel of all loggers", () => {
-		const logger1 = new MockLogger(LogLevel.error);
-		const logger2 = new MockLogger(LogLevel.default);
+		const logger1 = new MockLogger(LogLevel.essential);
+		const logger2 = new MockLogger(LogLevel.info);
 		const multiSink = createMultiSinkLogger({
 			loggers: [createChildLogger({ logger: logger1 }), logger2],
 		});
 		assert.strictEqual(
 			multiSink.minLogLevel,
-			LogLevel.default,
+			LogLevel.info,
 			"Min loglevel should be set correctly",
 		);
 
@@ -86,16 +86,16 @@ describe("MultiSinkLogger", () => {
 		);
 	});
 
-	it("MultiSink logger set the logLevel to default if not supplied with a log level", () => {
+	it("MultiSink logger set the logLevel to info if not supplied with a log level", () => {
 		const logger1 = new MockLogger();
 		const logger2 = new MockLogger();
 		const multiSink = createMultiSinkLogger({
 			loggers: [createChildLogger({ logger: logger1 }), logger2],
 		});
 		assert.strictEqual(
 			multiSink.minLogLevel,
-			LogLevel.default,
-			"Min loglevel should be set correctly to default",
+			LogLevel.info,
+			"Min loglevel should be set correctly to info",
 		);
 	});
 
@@ -107,15 +107,15 @@ describe("MultiSinkLogger", () => {
 		(multiSink as MultiSinkLogger).addLogger(new MockLogger());
 		assert.strictEqual(
 			multiSink.minLogLevel,
-			LogLevel.default,
-			"Min loglevel should be set correctly to default",
+			LogLevel.info,
+			"Min loglevel should be set correctly to info",
 		);
 
-		(multiSink as MultiSinkLogger).addLogger(new MockLogger(LogLevel.default));
+		(multiSink as MultiSinkLogger).addLogger(new MockLogger(LogLevel.info));
 		assert.strictEqual(
 			multiSink.minLogLevel,
-			LogLevel.default,
-			"Min loglevel should be set correctly to default",
+			LogLevel.info,
+			"Min loglevel should be set correctly to info",
 		);
 
 		(multiSink as MultiSinkLogger).addLogger(new MockLogger(LogLevel.verbose));