@fluidframework/container-runtime 2.10.0 → 2.12.0

package/src/summary/runWhileConnectedCoordinator.ts

@@ -3,13 +3,10 @@
  * Licensed under the MIT License.
  */
 
+import type { SummarizerStopReason } from "@fluidframework/container-runtime-definitions/internal";
 import { assert, Deferred } from "@fluidframework/core-utils/internal";
 
-import {
-	IConnectableRuntime,
-	ISummaryCancellationToken,
-	SummarizerStopReason,
-} from "./summarizerTypes.js";
+import { IConnectableRuntime, ISummaryCancellationToken } from "./summarizerTypes.js";
 
 /**
  * Similar to AbortController, but using promise instead of events

package/src/summary/runningSummarizer.ts

@@ -4,6 +4,12 @@
  */
 
 import { TypedEventEmitter } from "@fluid-internal/client-utils";
+import type {
+	ISummarizeEventProps,
+	ISummarizerEvents,
+	ISummarizerObservabilityProps,
+	SummarizerStopReason,
+} from "@fluidframework/container-runtime-definitions/internal";
 import { IDisposable, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
 import { assert, Deferred, PromiseTimer, delay } from "@fluidframework/core-utils/internal";
 import {
@@ -29,18 +35,15 @@ import {
 	IOnDemandSummarizeOptions,
 	IRefreshSummaryAckOptions,
 	ISubmitSummaryOptions,
-	ISummarizeEventProps,
 	ISummarizeHeuristicData,
 	ISummarizeHeuristicRunner,
 	ISummarizeOptions,
 	ISummarizeResults,
 	ISummarizeRunnerTelemetry,
 	ISummarizeTelemetryProperties,
-	ISummarizerEvents,
 	ISummarizerRuntime,
 	ISummaryCancellationToken,
 	SubmitSummaryResult,
-	SummarizerStopReason,
 	type IRetriableFailureError,
 } from "./summarizerTypes.js";
 import {
@@ -189,6 +192,13 @@ export class RunningSummarizer
 	/** The maximum number of summary attempts to do when submit summary fails. */
 	private readonly maxAttemptsForSubmitFailures: number;
 
+	/**
+	 * These are necessary to store outside of methods because of the logic around runnning a lastSummary.
+	 * We want the lastSummary to also be captured as "all attempts failed".
+	 */
+	private lastSummarizeFailureEventProps: Omit<ISummarizeEventProps, "result"> | undefined =
+		undefined;
+
 	private constructor(
 		baseLogger: ITelemetryBaseLogger,
 		private readonly summaryWatcher: IClientSummaryWatcher,
@@ -492,6 +502,8 @@ export class RunningSummarizer
 					// summarizeProps
 					{ summarizeReason: "lastSummary" },
 					{},
+					undefined,
+					true /* isLastSummary */,
 				);
 			}
 		}
@@ -502,6 +514,15 @@ export class RunningSummarizer
 		// submit summary. We should reconsider this flow and make summarizer move to exit faster.
 		// This resolves when the current pending summary gets an ack or fails.
 		await this.summarizingLock;
+
+		if (this.lastSummarizeFailureEventProps !== undefined) {
+			this.emit("summarizeAllAttemptsFailed", {
+				...this.lastSummarizeFailureEventProps,
+				numUnsummarizedRuntimeOps: this.heuristicData.numRuntimeOps,
+				numUnsummarizedNonRuntimeOps: this.heuristicData.numNonRuntimeOps,
+			});
+		}
+		this.lastSummarizeFailureEventProps = undefined;
 	}
 
 	private async waitStart() {
@@ -579,12 +600,14 @@ export class RunningSummarizer
 	 * @param options - summary options
 	 * @param cancellationToken - cancellation token to use to be able to cancel this summary, if needed
 	 * @param resultsBuilder - optional, result builder to use.
+	 * @param isLastSummary - optional, is the call to this method for a last summary when shutting down the summarizer?
 	 * @returns ISummarizeResult - result of running a summary.
 	 */
 	private trySummarizeOnce(
 		summarizeProps: ISummarizeTelemetryProperties,
 		options: ISummarizeOptions,
 		resultsBuilder = new SummarizeResultBuilder(),
+		isLastSummary = false,
 	): ISummarizeResults {
 		this.lockedSummaryAction(
 			() => {
@@ -604,7 +627,28 @@ export class RunningSummarizer
 				const summarizeResult = this.generator.summarize(summaryOptions, resultsBuilder);
 				// ensure we wait till the end of the process
 				const result = await summarizeResult.receivedSummaryAckOrNack;
-				if (!result.success) {
+
+				if (result.success) {
+					this.emit("summarize", {
+						result: "success",
+						currentAttempt: 1,
+						maxAttempts: 1,
+						numUnsummarizedRuntimeOps: this.heuristicData.numRuntimeOps,
+						numUnsummarizedNonRuntimeOps: this.heuristicData.numNonRuntimeOps,
+						isLastSummary,
+					});
+					this.lastSummarizeFailureEventProps = undefined;
+				} else {
+					this.emit("summarize", {
+						result: "failure",
+						currentAttempt: 1,
+						maxAttempts: 1,
+						error: result.error,
+						failureMessage: result.message,
+						numUnsummarizedRuntimeOps: this.heuristicData.numRuntimeOps,
+						numUnsummarizedNonRuntimeOps: this.heuristicData.numNonRuntimeOps,
+						isLastSummary,
+					});
 					this.mc.logger.sendErrorEvent(
 						{
 							eventName: "SummarizeFailed",
@@ -613,6 +657,14 @@ export class RunningSummarizer
 						},
 						result.error,
 					);
+					if (isLastSummary) {
+						this.lastSummarizeFailureEventProps = {
+							currentAttempt: (this.lastSummarizeFailureEventProps?.currentAttempt ?? 0) + 1,
+							maxAttempts: (this.lastSummarizeFailureEventProps?.currentAttempt ?? 0) + 1,
+							error: result.error,
+							failureMessage: result.message,
+						};
+					}
 				}
 			},
 			() => {
@@ -701,6 +753,7 @@ export class RunningSummarizer
 		let status: "success" | "failure" | "canceled" = "success";
 		let results: ISummarizeResults | undefined;
 		let error: IRetriableFailureError | undefined;
+		let failureMessage: string | undefined;
 		do {
 			currentAttempt++;
 			if (this.cancellationToken.cancelled) {
@@ -731,12 +784,16 @@ export class RunningSummarizer
 			// Emit "summarize" event for this failed attempt.
 			status = "failure";
 			error = ackNackResult.error;
+			failureMessage = ackNackResult.message;
 			retryAfterSeconds = error.retryAfterSeconds;
-			const eventProps: ISummarizeEventProps = {
+			const eventProps: ISummarizeEventProps & ISummarizerObservabilityProps = {
 				result: status,
 				currentAttempt,
 				maxAttempts,
 				error,
+				failureMessage,
+				numUnsummarizedRuntimeOps: this.heuristicData.numRuntimeOps,
+				numUnsummarizedNonRuntimeOps: this.heuristicData.numNonRuntimeOps,
 			};
 			this.emit("summarize", eventProps);
 
@@ -761,7 +818,13 @@ export class RunningSummarizer
 
 		// If the attempt was successful, emit "summarize" event and return. A failed attempt may be retried below.
 		if (status !== "failure") {
-			this.emit("summarize", { result: status, currentAttempt, maxAttempts });
+			this.emit("summarize", {
+				result: status,
+				currentAttempt,
+				maxAttempts,
+				numUnsummarizedRuntimeOps: this.heuristicData.numRuntimeOps,
+				numUnsummarizedNonRuntimeOps: this.heuristicData.numNonRuntimeOps,
+			});
 			return results;
 		}
 
@@ -772,14 +835,16 @@ export class RunningSummarizer
 			// Ack / nack is the final step, so if it succeeds we're done.
 			const ackNackResult = await summarizeResult.receivedSummaryAckOrNack;
 			status = ackNackResult.success ? "success" : "failure";
-			if (!ackNackResult.success) {
-				error = ackNackResult.error;
-			}
-			const eventProps: ISummarizeEventProps = {
+			error = ackNackResult.success ? undefined : ackNackResult.error;
+			failureMessage = ackNackResult.success ? undefined : ackNackResult.message;
+			const eventProps: ISummarizeEventProps & ISummarizerObservabilityProps = {
 				result: status,
 				currentAttempt,
 				maxAttempts,
-				error: ackNackResult.success ? undefined : ackNackResult.error,
+				error,
+				failureMessage,
+				numUnsummarizedRuntimeOps: this.heuristicData.numRuntimeOps,
+				numUnsummarizedNonRuntimeOps: this.heuristicData.numNonRuntimeOps,
 			};
 			this.emit("summarize", eventProps);
 			results = summarizeResult;
@@ -795,6 +860,12 @@ export class RunningSummarizer
 				},
 				error,
 			);
+			this.lastSummarizeFailureEventProps = {
+				currentAttempt,
+				maxAttempts,
+				error,
+				failureMessage,
+			};
 			this.stopSummarizerCallback("failToSummarize");
 		}
 		return results;

package/src/summary/summarizer.ts

@@ -4,6 +4,10 @@
  */
 
 import { TypedEventEmitter } from "@fluid-internal/client-utils";
+import type {
+	ISummarizerEvents,
+	SummarizerStopReason,
+} from "@fluidframework/container-runtime-definitions/internal";
 import { IFluidHandleContext } from "@fluidframework/core-interfaces/internal";
 import { Deferred } from "@fluidframework/core-utils/internal";
 import {
@@ -25,15 +29,12 @@ import {
 	IConnectableRuntime,
 	IEnqueueSummarizeOptions,
 	IOnDemandSummarizeOptions,
-	ISummarizeEventProps,
 	ISummarizeHeuristicData,
 	ISummarizeResults,
 	ISummarizer,
-	ISummarizerEvents,
 	ISummarizerInternalsProvider,
 	ISummarizerRuntime,
 	ISummarizingWarning,
-	SummarizerStopReason,
 } from "./summarizerTypes.js";
 import { SummaryCollection } from "./summaryCollection.js";
 import { SummarizeResultBuilder } from "./summaryGenerator.js";
@@ -107,9 +108,21 @@ export class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements
 
 	public async run(onBehalfOf: string): Promise<SummarizerStopReason> {
 		try {
-			return await this.runCore(onBehalfOf);
+			const stopReason = await this.runCore(onBehalfOf);
+			this.emit("summarizerStop", {
+				stopReason,
+				numUnsummarizedRuntimeOps: this._heuristicData?.numRuntimeOps,
+				numUnsummarizedNonRuntimeOps: this._heuristicData?.numNonRuntimeOps,
+			});
+			return stopReason;
 		} catch (error) {
 			this.stop("summarizerException");
+			this.emit("summarizerStop", {
+				stopReason: "summarizerException",
+				error,
+				numUnsummarizedRuntimeOps: this._heuristicData?.numRuntimeOps,
+				numUnsummarizedNonRuntimeOps: this._heuristicData?.numNonRuntimeOps,
+			});
 			throw SummarizingWarning.wrap(error, false /* logged */, this.logger);
 		} finally {
 			this.close();
@@ -148,9 +161,20 @@ export class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements
 		});
 
 		if (runCoordinator.cancelled) {
+			this.emit("summarizerStartupFailed", {
+				reason: await runCoordinator.waitCancelled,
+				numUnsummarizedRuntimeOps: this._heuristicData?.numRuntimeOps,
+				numUnsummarizedNonRuntimeOps: this._heuristicData?.numNonRuntimeOps,
+			});
 			return runCoordinator.waitCancelled;
 		}
 
+		this.emit("summarizerStart", {
+			onBehalfOf,
+			numUnsummarizedRuntimeOps: this._heuristicData?.numRuntimeOps,
+			numUnsummarizedNonRuntimeOps: this._heuristicData?.numNonRuntimeOps,
+		});
+
 		const runningSummarizer = await this.start(onBehalfOf, runCoordinator);
 
 		// Wait for either external signal to cancel, or loss of connectivity.
@@ -254,15 +278,11 @@ export class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements
 			this.runtime,
 		);
 		this.runningSummarizer = runningSummarizer;
-		this.runningSummarizer.on("summarize", this.handleSummarizeEvent);
+		this.setupForwardedEvents();
 		this.starting = false;
 		return runningSummarizer;
 	}
 
-	private readonly handleSummarizeEvent = (eventProps: ISummarizeEventProps) => {
-		this.emit("summarize", eventProps);
-	};
-
 	/**
 	 * Disposes of resources after running.  This cleanup will
 	 * clear any outstanding timers and reset some of the state
@@ -275,7 +295,7 @@ export class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements
 
 		this._disposed = true;
 		if (this.runningSummarizer) {
-			this.runningSummarizer.off("summarize", this.handleSummarizeEvent);
+			this.cleanupForwardedEvents();
 			this.runningSummarizer.dispose();
 			this.runningSummarizer = undefined;
 		}
@@ -355,4 +375,23 @@ export class Summarizer extends TypedEventEmitter<ISummarizerEvents> implements
 	public recordSummaryAttempt?(summaryRefSeqNum?: number) {
 		this._heuristicData?.recordAttempt(summaryRefSeqNum);
 	}
+
+	private readonly forwardedEvents = new Map<any, () => void>();
+
+	private setupForwardedEvents() {
+		["summarize", "summarizeAllAttemptsFailed"].forEach((event) => {
+			const listener = (...args: any[]) => {
+				this.emit(event, ...args);
+			};
+			this.runningSummarizer?.on(event as any, listener);
+			this.forwardedEvents.set(event, listener);
+		});
+	}
+
+	private cleanupForwardedEvents() {
+		this.forwardedEvents.forEach((listener, event) =>
+			this.runningSummarizer?.off(event, listener),
+		);
+		this.forwardedEvents.clear();
+	}
 }

package/src/summary/summarizerTypes.ts

@@ -7,6 +7,10 @@ import {
 	IDeltaManager,
 	ContainerWarning,
 } from "@fluidframework/container-definitions/internal";
+import type {
+	ISummarizerEvents as NewISummarizerEvents,
+	SummarizerStopReason as NewSummarizerStopReason,
+} from "@fluidframework/container-runtime-definitions/internal";
 import {
 	IEvent,
 	IEventProvider,
@@ -54,7 +58,7 @@ export interface ICancellationToken<T> {
  * @legacy
  * @alpha
  */
-export type ISummaryCancellationToken = ICancellationToken<SummarizerStopReason>;
+export type ISummaryCancellationToken = ICancellationToken<NewSummarizerStopReason>;
 
 /**
  * Data required to update internal tracking state after receiving a Summary Ack.
@@ -397,6 +401,7 @@ export type EnqueueSummarizeResult =
 /**
  * @legacy
  * @alpha
+ * @deprecated Use SummarizerStopReason from the "\@fluidframework/container-runtime-definitions" package
  */
 export type SummarizerStopReason =
 	/** Summarizer client failed to summarize in all attempts. */
@@ -427,6 +432,7 @@ export type SummarizerStopReason =
 /**
  * @legacy
  * @alpha
+ * @deprecated Use ISummarizeEventProps from the "\@fluidframework/container-runtime-definitions" package
  */
 export interface ISummarizeEventProps {
 	result: "success" | "failure" | "canceled";
@@ -438,6 +444,7 @@ export interface ISummarizeEventProps {
 /**
  * @legacy
  * @alpha
+ * @deprecated Use ISummarizerEvents from the "\@fluidframework/container-runtime-definitions" package
  */
 export interface ISummarizerEvents extends IEvent {
 	(event: "summarize", listener: (props: ISummarizeEventProps) => void);
@@ -447,7 +454,7 @@ export interface ISummarizerEvents extends IEvent {
  * @legacy
  * @alpha
  */
-export interface ISummarizer extends IEventProvider<ISummarizerEvents> {
+export interface ISummarizer extends IEventProvider<NewISummarizerEvents> {
 	/**
 	 * Allows {@link ISummarizer} to be used with our {@link @fluidframework/core-interfaces#FluidObject} pattern.
 	 */
@@ -458,12 +465,12 @@ export interface ISummarizer extends IEventProvider<ISummarizerEvents> {
 	 * Summarizer will finish current processes, which may take a while.
 	 * For example, summarizer may complete last summary before exiting.
 	 */
-	stop(reason: SummarizerStopReason): void;
+	stop(reason: NewSummarizerStopReason): void;
 
 	/* Closes summarizer. Any pending processes (summary in flight) are abandoned. */
 	close(): void;
 
-	run(onBehalfOf: string): Promise<SummarizerStopReason>;
+	run(onBehalfOf: string): Promise<NewSummarizerStopReason>;
 
 	/**
 	 * Attempts to generate a summary on demand. If already running, takes no action.

package/src/summary/summaryManager.ts

@@ -4,6 +4,10 @@
  */
 
 import { TypedEventEmitter } from "@fluid-internal/client-utils";
+import type {
+	ISummarizerEvents,
+	SummarizerStopReason,
+} from "@fluidframework/container-runtime-definitions/internal";
 import {
 	IDisposable,
 	IEvent,
@@ -26,11 +30,8 @@ import {
 	EnqueueSummarizeResult,
 	IEnqueueSummarizeOptions,
 	IOnDemandSummarizeOptions,
-	ISummarizeEventProps,
 	ISummarizeResults,
 	ISummarizer,
-	ISummarizerEvents,
-	SummarizerStopReason,
 } from "./summarizerTypes.js";
 import { SummaryCollection } from "./summaryCollection.js";
 
@@ -165,10 +166,6 @@ export class SummaryManager
 		this.refreshSummarizer();
 	};
 
-	private readonly handleSummarizeEvent = (eventProps: ISummarizeEventProps) => {
-		this.emit("summarize", eventProps);
-	};
-
 	private static readonly isStartingOrRunning = (state: SummaryManagerState) =>
 		state === SummaryManagerState.Starting || state === SummaryManagerState.Running;
 
@@ -271,7 +268,7 @@ export class SummaryManager
 
 				const summarizer = await this.createSummarizerFn();
 				this.summarizer = summarizer;
-				this.summarizer.on("summarize", this.handleSummarizeEvent);
+				this.setupForwardedEvents();
 
 				// Re-validate that it need to be running. Due to asynchrony, it may be not the case anymore
 				// If we can't run the LastSummary, simply return as to avoid paying the cost of launching
@@ -345,7 +342,7 @@ export class SummaryManager
 				assert(this.state !== SummaryManagerState.Off, 0x264 /* "Expected: Not Off" */);
 				this.state = SummaryManagerState.Off;
 
-				this.summarizer?.off("summarize", this.handleSummarizeEvent);
+				this.cleanupForwardedEvents();
 				this.summarizer?.close();
 				this.summarizer = undefined;
 
@@ -448,7 +445,30 @@ export class SummaryManager
 		this.clientElection.off("electedSummarizerChanged", this.refreshSummarizer);
 		this.connectedState.off("connected", this.handleConnected);
 		this.connectedState.off("disconnected", this.handleDisconnected);
-		this.summarizer?.off("summarize", this.handleSummarizeEvent);
+		this.cleanupForwardedEvents();
 		this._disposed = true;
 	}
+
+	private readonly forwardedEvents = new Map<any, () => void>();
+
+	private setupForwardedEvents() {
+		[
+			"summarize",
+			"summarizeAllAttemptsFailed",
+			"summarizerStop",
+			"summarizerStart",
+			"summarizerStartupFailed",
+		].forEach((event) => {
+			const listener = (...args: any[]) => {
+				this.emit(event, ...args);
+			};
+			this.summarizer?.on(event as any, listener);
+			this.forwardedEvents.set(event, listener);
+		});
+	}
+
+	private cleanupForwardedEvents() {
+		this.forwardedEvents.forEach((listener, event) => this.summarizer?.off(event, listener));
+		this.forwardedEvents.clear();
+	}
 }