refactor(gitrest): Add stage traces to the Git write summary flow (#25954)

## Description

After some recent difficulties in narrowing down performance issues in
the summary flow, this PR takes the first step to making that easier in
the future by adding stage traces to the summary flow. This will allow
us to more easily analyze where a problem is occurring.

## Reviewer Guidance

Bumped server package versions to consume newly shared `StageTrace` from
services-core

Author: znewton

server/gitrest/packages/gitrest-base/package.json

@@ -52,15 +52,15 @@
 	},
 	"dependencies": {
 		"@fluidframework/common-utils": "^1.1.1",
-		"@fluidframework/gitresources": "6.0.0-340759",
-		"@fluidframework/protocol-base": "6.0.0-340759",
+		"@fluidframework/gitresources": "8.0.0-366087",
+		"@fluidframework/protocol-base": "8.0.0-366087",
 		"@fluidframework/protocol-definitions": "^3.2.0",
-		"@fluidframework/server-services-client": "6.0.0-340759",
-		"@fluidframework/server-services-core": "6.0.0-340759",
-		"@fluidframework/server-services-shared": "6.0.0-340759",
-		"@fluidframework/server-services-telemetry": "6.0.0-340759",
-		"@fluidframework/server-services-utils": "6.0.0-340759",
-		"@fluidframework/server-test-utils": "6.0.0-340759",
+		"@fluidframework/server-services-client": "8.0.0-366087",
+		"@fluidframework/server-services-core": "8.0.0-366087",
+		"@fluidframework/server-services-shared": "8.0.0-366087",
+		"@fluidframework/server-services-telemetry": "8.0.0-366087",
+		"@fluidframework/server-services-utils": "8.0.0-366087",
+		"@fluidframework/server-test-utils": "8.0.0-366087",
 		"async-mutex": "^0.3.2",
 		"axios": "^1.8.4",
 		"body-parser": "^1.20.3",

server/gitrest/packages/gitrest-base/src/utils/gitWholeSummaryManager.ts

@@ -9,6 +9,7 @@ import {
 	NetworkError,
 	isNetworkError,
 } from "@fluidframework/server-services-client";
+import { StageTrace } from "@fluidframework/server-services-core";
 import { Lumberjack } from "@fluidframework/server-services-telemetry";
 
 import type { IRepositoryManager, IFileSystemManager } from "./definitions";
@@ -18,6 +19,7 @@ import {
 	Constants,
 	type ISummaryWriteFeatureFlags,
 	type IWriteSummaryInfo,
+	WriteSummaryTraceStage,
 	isChannelSummary,
 	isContainerSummary,
 	readSummary,
@@ -106,6 +108,9 @@ export class GitWholeSummaryManager {
 			GitRestLumberEventName.WholeSummaryManagerWriteSummary,
 			lumberjackProperties,
 		);
+		const writeSummaryTrace = new StageTrace<WriteSummaryTraceStage>(
+			WriteSummaryTraceStage.WriteSummaryStarted,
+		);
 		try {
 			if (isChannelSummary(payload)) {
 				lumberjackProperties.summaryType = "channel";
@@ -119,7 +124,9 @@ export class GitWholeSummaryManager {
 						lumberjackProperties,
 					},
 					this.summaryWriteFeatureFlags,
+					writeSummaryTrace,
 				);
+				writeSummaryMetric.setProperty("summaryTrace", writeSummaryTrace);
 				writeSummaryMetric.setProperty("treeSha", writeSummaryInfo.writeSummaryResponse.id);
 				writeSummaryMetric.success(
 					"GitWholeSummaryManager succeeded in writing channel summary",
@@ -140,6 +147,7 @@ export class GitWholeSummaryManager {
 					},
 					this.summaryWriteFeatureFlags,
 				);
+				writeSummaryMetric.setProperty("summaryTrace", writeSummaryTrace);
 				writeSummaryMetric.setProperty("newDocument", writeSummaryInfo.isNew);
 				writeSummaryMetric.setProperty(
 					"commitSha",
@@ -156,6 +164,7 @@ export class GitWholeSummaryManager {
 			});
 			throw new NetworkError(400, `Unknown Summary Type: ${payload.type}`);
 		} catch (error: any) {
+			writeSummaryMetric.setProperty("summaryTrace", writeSummaryTrace);
 			writeSummaryMetric.error("GitWholeSummaryManager failed to write summary", error);
 			throw error;
 		}

server/gitrest/packages/gitrest-base/src/utils/wholeSummary/definitions.ts

@@ -48,3 +48,38 @@ export interface IFullGitTree {
 	 */
 	parsedFullTreeBlobs: boolean;
 }
+
+export enum WriteSummaryTraceStage {
+	/**
+	 * Summary write operation started, no logic executed yet.
+	 */
+	WriteSummaryStarted = "WriteSummaryStarted",
+	/**
+	 * Retrieved document's Git Ref from storage (if it existed).
+	 * This is a no-op in some scenarios, like on initial summary.
+	 */
+	DocRefRetrieved = "DocRefRetrieved",
+	/**
+	 * Computed the Git tree entries for the summary tree to be written.
+	 * This includes performing any "low IO" logic if enabled.
+	 */
+	ComputedTreeEntries = "ComputedTreeEntries",
+	/**
+	 * Successfully wrote the summary tree to Git storage.
+	 * This includes writing any blobs and tree nodes to storage.
+	 */
+	WroteSummaryTree = "WroteSummaryTree",
+	/**
+	 * Created a new commit referencing the written summary tree.
+	 */
+	CreatedNewSummaryVersion = "CreatedNewSummaryVersion",
+	/**
+	 * Created or updated the document Git Ref to point to the new commit.
+	 */
+	CreatedOrUpdatedDocRef = "CreatedOrUpdatedDocRef",
+	/**
+	 * Converted the full Git tree into a Whole Flat Summary structure to be returned
+	 * to the caller.
+	 */
+	ConvertedToWholeFlatSummary = "ConvertedToWholeFlatSummary",
+}

server/gitrest/packages/gitrest-base/src/utils/wholeSummary/index.ts

@@ -4,6 +4,7 @@
  */
 
 export { Constants } from "./constants";
+export { WriteSummaryTraceStage } from "./definitions";
 export { readSummary } from "./readWholeSummary";
 export {
 	ISummaryWriteFeatureFlags,

server/gitrest/packages/gitrest-base/src/utils/wholeSummary/writeWholeSummary.ts

@@ -10,6 +10,7 @@ import type {
 	IWriteSummaryResponse,
 	WholeSummaryTreeEntry,
 } from "@fluidframework/server-services-client";
+import { StageTrace } from "@fluidframework/server-services-core";
 import { Lumberjack } from "@fluidframework/server-services-telemetry";
 
 import { GitRestLumberEventName } from "../gitrestTelemetryDefinitions";
@@ -19,7 +20,12 @@ import {
 	type IWriteSummaryTreeOptions,
 	writeSummaryTree as writeSummaryTreeCore,
 } from "./coreWriteUtils";
-import type { IFullGitTree, ISummaryVersion, IWholeSummaryOptions } from "./definitions";
+import {
+	IFullGitTree,
+	ISummaryVersion,
+	IWholeSummaryOptions,
+	WriteSummaryTraceStage,
+} from "./definitions";
 import { computeLowIoSummaryTreeEntries } from "./lowIoWriteUtils";
 
 /**
@@ -127,6 +133,7 @@ async function writeSummaryTree(
 	payload: IWholeSummaryPayload,
 	documentRef: IRef | undefined,
 	options: IWholeSummaryOptions & { precomputeFullTree: boolean; useLowIoWrite: boolean },
+	stageTrace?: StageTrace<WriteSummaryTraceStage>,
 ): Promise<IFullGitTree> {
 	const writeSummaryTreeOptions: IWriteSummaryTreeOptions = {
 		repoManager: options.repoManager,
@@ -145,6 +152,7 @@ async function writeSummaryTree(
 		writeSummaryTreeOptions,
 		options,
 	);
+	stageTrace?.stampStage(WriteSummaryTraceStage.ComputedTreeEntries);
 
 	const writeSummaryTreeMetric = Lumberjack.newLumberMetric(
 		GitRestLumberEventName.WriteSummaryTree,
@@ -168,15 +176,23 @@ export async function writeChannelSummary(
 	payload: IWholeSummaryPayload,
 	options: IWholeSummaryOptions,
 	featureFlags: ISummaryWriteFeatureFlags,
+	stageTrace?: StageTrace<WriteSummaryTraceStage>,
 ): Promise<IWriteSummaryInfo> {
 	const useLowIoWrite = featureFlags.enableLowIoWrite === true;
 	// We need the document Ref to write channel with LowIo so that we can access pointers.
 	const documentRef: IRef | undefined = useLowIoWrite ? await getDocRef(options) : undefined;
-	const fullGitTree = await writeSummaryTree(payload, documentRef, {
-		...options,
-		precomputeFullTree: false,
-		useLowIoWrite,
-	});
+	stageTrace?.stampStage(WriteSummaryTraceStage.DocRefRetrieved);
+	const fullGitTree = await writeSummaryTree(
+		payload,
+		documentRef,
+		{
+			...options,
+			precomputeFullTree: false,
+			useLowIoWrite,
+		},
+		stageTrace,
+	);
+	stageTrace?.stampStage(WriteSummaryTraceStage.WroteSummaryTree);
 	return {
 		isNew: false,
 		writeSummaryResponse: {
@@ -291,23 +307,31 @@ export async function writeContainerSummary(
 	isInitial: boolean,
 	options: IWholeSummaryOptions,
 	featureFlags: ISummaryWriteFeatureFlags,
+	stageTrace?: StageTrace<WriteSummaryTraceStage>,
 ): Promise<IWriteSummaryInfo> {
 	// Ref will not exist for an initial summary, so do not bother checking.
 	const documentRef: IRef | undefined =
 		featureFlags.optimizeForInitialSummary && isInitial === true
 			? undefined
 			: await getDocRef(options);
+	stageTrace?.stampStage(WriteSummaryTraceStage.DocRefRetrieved);
 	const isNewDocument = !documentRef && payload.sequenceNumber === 0;
 	const useLowIoWrite =
 		featureFlags.enableLowIoWrite === true ||
 		(isNewDocument && featureFlags.enableLowIoWrite === "initial");
 
 	// Write the container summary tree into storage.
-	const fullGitTree = await writeSummaryTree(payload, documentRef, {
-		...options,
-		precomputeFullTree: true,
-		useLowIoWrite,
-	});
+	const fullGitTree = await writeSummaryTree(
+		payload,
+		documentRef,
+		{
+			...options,
+			precomputeFullTree: true,
+			useLowIoWrite,
+		},
+		stageTrace,
+	);
+	stageTrace?.stampStage(WriteSummaryTraceStage.WroteSummaryTree);
 
 	// Create a new commit referencing the container summary tree.
 	const { id: versionId, treeId } = await createNewSummaryVersion(
@@ -317,11 +341,14 @@ export async function writeContainerSummary(
 		payload.sequenceNumber,
 		options,
 	);
+	stageTrace?.stampStage(WriteSummaryTraceStage.CreatedNewSummaryVersion);
 
 	// Create or update the document ref to reference the new commit.
 	await createOrUpdateRef(documentRef, versionId, options);
+	stageTrace?.stampStage(WriteSummaryTraceStage.CreatedOrUpdatedDocRef);
 
 	const fullSummaryTree = convertFullGitTreeToFullSummaryTree(fullGitTree);
+	stageTrace?.stampStage(WriteSummaryTraceStage.ConvertedToWholeFlatSummary);
 	const wholeFlatSummary: IWholeFlatSummary = {
 		id: versionId,
 		trees: [

server/gitrest/packages/gitrest/package.json

@@ -28,8 +28,8 @@
 	},
 	"dependencies": {
 		"@fluidframework/gitrest-base": "workspace:~",
-		"@fluidframework/server-services-shared": "6.0.0-340759",
-		"@fluidframework/server-services-utils": "6.0.0-340759",
+		"@fluidframework/server-services-shared": "8.0.0-366087",
+		"@fluidframework/server-services-utils": "8.0.0-366087",
 		"body-parser": "^1.20.3",
 		"compression": "^1.7.3",
 		"cors": "^2.8.5",