@fluidframework/container-runtime 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.224419

package/lib/gc/gcSummaryStateTracker.mjs

@@ -0,0 +1,209 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { SummaryType } from "@fluidframework/protocol-definitions";
+import { gcBlobPrefix, gcDeletedBlobKey, gcTombstoneBlobKey, gcTreeKey, } from "@fluidframework/runtime-definitions";
+import { mergeStats, SummaryTreeBuilder } from "@fluidframework/runtime-utils";
+import { generateSortedGCState } from "./gcHelpers.mjs";
+export const gcStateBlobKey = `${gcBlobPrefix}_root`;
+/**
+ * Encapsulates the garbage collection state that is tracked across summaries.
+ * It maintains the GC state as per the latest summary in by the server. It updates state when a summary tracked by this
+ * client is acked by the server or from a snapshot is downloaded from the server.
+ * On summarize, it decides whether to write new state or re-use previous summary's state.
+ */
+export class GCSummaryStateTracker {
+    constructor(
+    // Tells whether GC should run or not.
+    configs, 
+    // Tells whether GC was run in the base snapshot this container loaded from.
+    wasGCRunInBaseSnapshot) {
+        this.configs = configs;
+        // Tracks the count of data stores whose state updated since the last summary, i.e., they went from referenced
+        // to unreferenced or vice-versa.
+        this.updatedDSCountSinceLastSummary = 0;
+        this.wasGCRunInLatestSummary = wasGCRunInBaseSnapshot;
+        // For existing document, the latest summary is the one that we loaded from. So, use its GC version as the
+        // latest tracked GC version. For new documents, we will be writing the first summary with the current version.
+        this.latestSummaryGCVersion =
+            this.configs.gcVersionInBaseSnapshot ?? this.configs.gcVersionInEffect;
+    }
+    /**
+     * Tells whether the GC state needs to be reset. This can happen under 3 conditions:
+     *
+     * 1. The base snapshot contains GC state but GC is disabled. This will happen the first time GC is disabled after
+     * it was enabled before. GC state needs to be removed from summary and all nodes should be marked referenced.
+     *
+     * 2. The base snapshot does not have GC state but GC is enabled. This will happen the very first time GC runs on
+     * a document and the first time GC is enabled after is was disabled before.
+     *
+     * 3. GC is enabled and the latest summary state is refreshed from a snapshot that had GC disabled and vice-versa.
+     *
+     * Note that the state will be reset only once for the first summary generated after this returns true. After that,
+     * this will return false.
+     */
+    get doesGCStateNeedReset() {
+        return this.wasGCRunInLatestSummary !== this.configs.shouldRunGC;
+    }
+    /**
+     * Tells whether the GC state needs to be reset in the next summary. We need to do this if:
+     *
+     * 1. GC was enabled and is now disabled. The GC state needs to be removed and everything becomes referenced.
+     *
+     * 2. GC was disabled and is now enabled. The GC state needs to be regenerated and added to summary.
+     *
+     * 3. GC is enabled and the latest summary state is refreshed from a snapshot that had GC disabled and vice-versa.
+     *
+     * 4. The GC version in the latest summary is different from the current GC version. This can happen if:
+     *
+     * 4.1. The summary this client loaded with has data from a different GC version.
+     *
+     * 4.2. This client's latest summary was updated from a snapshot that has a different GC version.
+     */
+    get doesSummaryStateNeedReset() {
+        return (this.doesGCStateNeedReset ||
+            (this.configs.shouldRunGC &&
+                this.latestSummaryGCVersion !== this.configs.gcVersionInEffect));
+    }
+    /**
+     * Called during GC initialization. Initialize the latest summary data from the base snapshot data.
+     */
+    initializeBaseState(baseSnapshotData) {
+        if (baseSnapshotData === undefined) {
+            return;
+        }
+        // If tracking state across summaries, update latest summary data from the snapshot's GC data.
+        this.latestSummaryData = {
+            serializedGCState: baseSnapshotData.gcState
+                ? JSON.stringify(generateSortedGCState(baseSnapshotData.gcState))
+                : undefined,
+            serializedTombstones: JSON.stringify(baseSnapshotData.tombstones),
+            serializedDeletedNodes: JSON.stringify(baseSnapshotData.deletedNodes),
+        };
+    }
+    /**
+     * Summarizes three component of the GC data - GC state, tombstones and deleted nodes.
+     * It does incremental summary, i.e., it writes summary tree / summary blob only for the component that changed.
+     * For components that did not change, a summary handle is returned that points to the previous successful summary.
+     * If none of the components changed, it returns a summary handle for the entire GC data.
+     */
+    summarize(fullTree, trackState, gcState, deletedNodes, tombstones) {
+        if (!this.configs.shouldRunGC) {
+            return;
+        }
+        const serializedGCState = JSON.stringify(generateSortedGCState(gcState));
+        // Serialize and write deleted nodes, if any. This is done irrespective of whether sweep is enabled or not so
+        // to identify deleted nodes' usage.
+        const serializedDeletedNodes = deletedNodes.size > 0 ? JSON.stringify(Array.from(deletedNodes).sort()) : undefined;
+        // If running in tombstone mode, serialize and write tombstones, if any.
+        const serializedTombstones = this.configs.tombstoneMode
+            ? tombstones.length > 0
+                ? JSON.stringify(tombstones.sort())
+                : undefined
+            : undefined;
+        /**
+         * Incremental summary of GC data - If none of GC state, deleted nodes or tombstones changed since last summary,
+         * write summary handle instead of summary tree for GC.
+         * Otherwise, write the GC summary tree. In the tree, for each of these that changed, write a summary blob and
+         * for each of these that did not change, write a summary handle.
+         */
+        this.pendingSummaryData = {
+            serializedGCState,
+            serializedTombstones,
+            serializedDeletedNodes,
+        };
+        if (trackState && !fullTree && this.latestSummaryData !== undefined) {
+            // If nothing changed since last summary, send a summary handle for the entire GC data.
+            if (this.latestSummaryData.serializedGCState === serializedGCState &&
+                this.latestSummaryData.serializedTombstones === serializedTombstones &&
+                this.latestSummaryData.serializedDeletedNodes === serializedDeletedNodes) {
+                const stats = mergeStats();
+                stats.handleNodeCount++;
+                return {
+                    summary: {
+                        type: SummaryType.Handle,
+                        handle: `/${gcTreeKey}`,
+                        handleType: SummaryType.Tree,
+                    },
+                    stats,
+                };
+            }
+            // If some state changed, build a GC summary tree.
+            return this.buildGCSummaryTree(serializedGCState, serializedTombstones, serializedDeletedNodes, true /* trackState */);
+        }
+        // If not tracking GC state, build a GC summary tree without any summary handles.
+        return this.buildGCSummaryTree(serializedGCState, serializedTombstones, serializedDeletedNodes, false /* trackState */);
+    }
+    /**
+     * Builds the GC summary tree which contains GC state, deleted nodes and tombstones.
+     * If trackState is false, all of GC state, deleted nodes and tombstones are written as summary blobs.
+     * If trackState is true, only states that changed are written. Rest are written as handles.
+     * @param serializedGCState - The GC state serialized as string.
+     * @param serializedTombstones - The tombstone state serialized as string.
+     * @param serializedDeletedNodes - Deleted nodes serialized as string.
+     * @param trackState - Whether we are tracking GC state across summaries.
+     * @returns the GC summary tree.
+     */
+    buildGCSummaryTree(serializedGCState, serializedTombstones, serializedDeletedNodes, trackState) {
+        const builder = new SummaryTreeBuilder();
+        // If the GC state hasn't changed, write a summary handle, else write a summary blob for it.
+        if (this.latestSummaryData?.serializedGCState === serializedGCState && trackState) {
+            builder.addHandle(gcStateBlobKey, SummaryType.Blob, `/${gcTreeKey}/${gcStateBlobKey}`);
+        }
+        else {
+            builder.addBlob(gcStateBlobKey, serializedGCState);
+        }
+        // If tombstones exist, write a summary handle if it hasn't changed. If it has changed, write a
+        // summary blob.
+        if (serializedTombstones !== undefined) {
+            if (this.latestSummaryData?.serializedTombstones === serializedTombstones &&
+                trackState) {
+                builder.addHandle(gcTombstoneBlobKey, SummaryType.Blob, `/${gcTreeKey}/${gcTombstoneBlobKey}`);
+            }
+            else {
+                builder.addBlob(gcTombstoneBlobKey, serializedTombstones);
+            }
+        }
+        // If there are no deleted nodes, return the summary tree.
+        if (serializedDeletedNodes === undefined) {
+            return builder.getSummaryTree();
+        }
+        // If the deleted nodes hasn't changed, write a summary handle, else write a summary blob for it.
+        if (this.latestSummaryData?.serializedDeletedNodes === serializedDeletedNodes &&
+            trackState) {
+            builder.addHandle(gcDeletedBlobKey, SummaryType.Blob, `/${gcTreeKey}/${gcDeletedBlobKey}`);
+        }
+        else {
+            builder.addBlob(gcDeletedBlobKey, serializedDeletedNodes);
+        }
+        return builder.getSummaryTree();
+    }
+    /**
+     * Called to refresh the latest summary state. This happens when either a pending summary is acked.
+     */
+    async refreshLatestSummary(result) {
+        if (!result.isSummaryTracked) {
+            return;
+        }
+        // If the summary is tracked, this client is the one that generated it. So, update wasGCRunInLatestSummary.
+        // Note that this has to be updated if GC did not run too. Otherwise, `gcStateNeedsReset` will always return
+        // true in scenarios where GC is currently disabled but enabled in the snapshot we loaded from.
+        this.wasGCRunInLatestSummary = this.configs.shouldRunGC;
+        if (!this.configs.shouldRunGC) {
+            return;
+        }
+        this.latestSummaryGCVersion = this.configs.gcVersionInEffect;
+        this.latestSummaryData = this.pendingSummaryData;
+        this.pendingSummaryData = undefined;
+        this.updatedDSCountSinceLastSummary = 0;
+        return;
+    }
+    /**
+     * Called to update the state from a GC run's stats. Used to update the count of data stores whose state updated.
+     */
+    updateStateFromGCRunStats(stats) {
+        this.updatedDSCountSinceLastSummary += stats.updatedDataStoreCount;
+    }
+}
+//# sourceMappingURL=gcSummaryStateTracker.mjs.map

package/lib/gc/gcSummaryStateTracker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcSummaryStateTracker.mjs","sourceRoot":"","sources":["../../src/gc/gcSummaryStateTracker.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { SummaryType } from \"@fluidframework/protocol-definitions\";\nimport {\n\tgcBlobPrefix,\n\tgcDeletedBlobKey,\n\tgcTombstoneBlobKey,\n\tgcTreeKey,\n\tISummarizeResult,\n\tISummaryTreeWithStats,\n} from \"@fluidframework/runtime-definitions\";\nimport { mergeStats, SummaryTreeBuilder } from \"@fluidframework/runtime-utils\";\nimport { IRefreshSummaryResult } from \"../summary\";\nimport { GCVersion, IGarbageCollectorConfigs, IGCStats } from \"./gcDefinitions\";\nimport { generateSortedGCState } from \"./gcHelpers\";\nimport { IGarbageCollectionSnapshotData, IGarbageCollectionState } from \"./gcSummaryDefinitions\";\n\nexport const gcStateBlobKey = `${gcBlobPrefix}_root`;\n\n/**\n * The GC data that is tracked for a summary.\n */\nexport interface IGCSummaryTrackingData {\n\tserializedGCState: string | undefined;\n\tserializedTombstones: string | undefined;\n\tserializedDeletedNodes: string | undefined;\n}\n\n/**\n * Encapsulates the garbage collection state that is tracked across summaries.\n * It maintains the GC state as per the latest summary in by the server. It updates state when a summary tracked by this\n * client is acked by the server or from a snapshot is downloaded from the server.\n * On summarize, it decides whether to write new state or re-use previous summary's state.\n */\nexport class GCSummaryStateTracker {\n\t// This is the version of GC data in the latest summary being tracked.\n\tprivate latestSummaryGCVersion: GCVersion;\n\n\t// Keeps track of the GC data from the latest summary successfully acked by the server.\n\tprivate latestSummaryData: IGCSummaryTrackingData | undefined;\n\t// Keeps track of the GC data from the last summary submitted to the server but not yet acked.\n\tprivate pendingSummaryData: IGCSummaryTrackingData | undefined;\n\n\t// Tracks whether there was GC was run in latest summary being tracked.\n\tprivate wasGCRunInLatestSummary: boolean;\n\n\t// Tracks the count of data stores whose state updated since the last summary, i.e., they went from referenced\n\t// to unreferenced or vice-versa.\n\tpublic updatedDSCountSinceLastSummary: number = 0;\n\n\tconstructor(\n\t\t// Tells whether GC should run or not.\n\t\tprivate readonly configs: Pick<\n\t\t\tIGarbageCollectorConfigs,\n\t\t\t\"shouldRunGC\" | \"tombstoneMode\" | \"gcVersionInBaseSnapshot\" | \"gcVersionInEffect\"\n\t\t>,\n\t\t// Tells whether GC was run in the base snapshot this container loaded from.\n\t\twasGCRunInBaseSnapshot: boolean,\n\t) {\n\t\tthis.wasGCRunInLatestSummary = wasGCRunInBaseSnapshot;\n\t\t// For existing document, the latest summary is the one that we loaded from. So, use its GC version as the\n\t\t// latest tracked GC version. For new documents, we will be writing the first summary with the current version.\n\t\tthis.latestSummaryGCVersion =\n\t\t\tthis.configs.gcVersionInBaseSnapshot ?? this.configs.gcVersionInEffect;\n\t}\n\n\t/**\n\t * Tells whether the GC state needs to be reset. This can happen under 3 conditions:\n\t *\n\t * 1. The base snapshot contains GC state but GC is disabled. This will happen the first time GC is disabled after\n\t * it was enabled before. GC state needs to be removed from summary and all nodes should be marked referenced.\n\t *\n\t * 2. The base snapshot does not have GC state but GC is enabled. This will happen the very first time GC runs on\n\t * a document and the first time GC is enabled after is was disabled before.\n\t *\n\t * 3. GC is enabled and the latest summary state is refreshed from a snapshot that had GC disabled and vice-versa.\n\t *\n\t * Note that the state will be reset only once for the first summary generated after this returns true. After that,\n\t * this will return false.\n\t */\n\tpublic get doesGCStateNeedReset(): boolean {\n\t\treturn this.wasGCRunInLatestSummary !== this.configs.shouldRunGC;\n\t}\n\n\t/**\n\t * Tells whether the GC state needs to be reset in the next summary. We need to do this if:\n\t *\n\t * 1. GC was enabled and is now disabled. The GC state needs to be removed and everything becomes referenced.\n\t *\n\t * 2. GC was disabled and is now enabled. The GC state needs to be regenerated and added to summary.\n\t *\n\t * 3. GC is enabled and the latest summary state is refreshed from a snapshot that had GC disabled and vice-versa.\n\t *\n\t * 4. The GC version in the latest summary is different from the current GC version. This can happen if:\n\t *\n\t * 4.1. The summary this client loaded with has data from a different GC version.\n\t *\n\t * 4.2. This client's latest summary was updated from a snapshot that has a different GC version.\n\t */\n\tpublic get doesSummaryStateNeedReset(): boolean {\n\t\treturn (\n\t\t\tthis.doesGCStateNeedReset ||\n\t\t\t(this.configs.shouldRunGC &&\n\t\t\t\tthis.latestSummaryGCVersion !== this.configs.gcVersionInEffect)\n\t\t);\n\t}\n\n\t/**\n\t * Called during GC initialization. Initialize the latest summary data from the base snapshot data.\n\t */\n\tpublic initializeBaseState(baseSnapshotData: IGarbageCollectionSnapshotData | undefined) {\n\t\tif (baseSnapshotData === undefined) {\n\t\t\treturn;\n\t\t}\n\n\t\t// If tracking state across summaries, update latest summary data from the snapshot's GC data.\n\t\tthis.latestSummaryData = {\n\t\t\tserializedGCState: baseSnapshotData.gcState\n\t\t\t\t? JSON.stringify(generateSortedGCState(baseSnapshotData.gcState))\n\t\t\t\t: undefined,\n\t\t\tserializedTombstones: JSON.stringify(baseSnapshotData.tombstones),\n\t\t\tserializedDeletedNodes: JSON.stringify(baseSnapshotData.deletedNodes),\n\t\t};\n\t}\n\n\t/**\n\t * Summarizes three component of the GC data - GC state, tombstones and deleted nodes.\n\t * It does incremental summary, i.e., it writes summary tree / summary blob only for the component that changed.\n\t * For components that did not change, a summary handle is returned that points to the previous successful summary.\n\t * If none of the components changed, it returns a summary handle for the entire GC data.\n\t */\n\tpublic summarize(\n\t\tfullTree: boolean,\n\t\ttrackState: boolean,\n\t\tgcState: IGarbageCollectionState,\n\t\tdeletedNodes: Set<string>,\n\t\ttombstones: string[],\n\t): ISummarizeResult | undefined {\n\t\tif (!this.configs.shouldRunGC) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst serializedGCState = JSON.stringify(generateSortedGCState(gcState));\n\t\t// Serialize and write deleted nodes, if any. This is done irrespective of whether sweep is enabled or not so\n\t\t// to identify deleted nodes' usage.\n\t\tconst serializedDeletedNodes =\n\t\t\tdeletedNodes.size > 0 ? JSON.stringify(Array.from(deletedNodes).sort()) : undefined;\n\t\t// If running in tombstone mode, serialize and write tombstones, if any.\n\t\tconst serializedTombstones = this.configs.tombstoneMode\n\t\t\t? tombstones.length > 0\n\t\t\t\t? JSON.stringify(tombstones.sort())\n\t\t\t\t: undefined\n\t\t\t: undefined;\n\n\t\t/**\n\t\t * Incremental summary of GC data - If none of GC state, deleted nodes or tombstones changed since last summary,\n\t\t * write summary handle instead of summary tree for GC.\n\t\t * Otherwise, write the GC summary tree. In the tree, for each of these that changed, write a summary blob and\n\t\t * for each of these that did not change, write a summary handle.\n\t\t */\n\t\tthis.pendingSummaryData = {\n\t\t\tserializedGCState,\n\t\t\tserializedTombstones,\n\t\t\tserializedDeletedNodes,\n\t\t};\n\n\t\tif (trackState && !fullTree && this.latestSummaryData !== undefined) {\n\t\t\t// If nothing changed since last summary, send a summary handle for the entire GC data.\n\t\t\tif (\n\t\t\t\tthis.latestSummaryData.serializedGCState === serializedGCState &&\n\t\t\t\tthis.latestSummaryData.serializedTombstones === serializedTombstones &&\n\t\t\t\tthis.latestSummaryData.serializedDeletedNodes === serializedDeletedNodes\n\t\t\t) {\n\t\t\t\tconst stats = mergeStats();\n\t\t\t\tstats.handleNodeCount++;\n\t\t\t\treturn {\n\t\t\t\t\tsummary: {\n\t\t\t\t\t\ttype: SummaryType.Handle,\n\t\t\t\t\t\thandle: `/${gcTreeKey}`,\n\t\t\t\t\t\thandleType: SummaryType.Tree,\n\t\t\t\t\t},\n\t\t\t\t\tstats,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\t// If some state changed, build a GC summary tree.\n\t\t\treturn this.buildGCSummaryTree(\n\t\t\t\tserializedGCState,\n\t\t\t\tserializedTombstones,\n\t\t\t\tserializedDeletedNodes,\n\t\t\t\ttrue /* trackState */,\n\t\t\t);\n\t\t}\n\t\t// If not tracking GC state, build a GC summary tree without any summary handles.\n\t\treturn this.buildGCSummaryTree(\n\t\t\tserializedGCState,\n\t\t\tserializedTombstones,\n\t\t\tserializedDeletedNodes,\n\t\t\tfalse /* trackState */,\n\t\t);\n\t}\n\n\t/**\n\t * Builds the GC summary tree which contains GC state, deleted nodes and tombstones.\n\t * If trackState is false, all of GC state, deleted nodes and tombstones are written as summary blobs.\n\t * If trackState is true, only states that changed are written. Rest are written as handles.\n\t * @param serializedGCState - The GC state serialized as string.\n\t * @param serializedTombstones - The tombstone state serialized as string.\n\t * @param serializedDeletedNodes - Deleted nodes serialized as string.\n\t * @param trackState - Whether we are tracking GC state across summaries.\n\t * @returns the GC summary tree.\n\t */\n\tprivate buildGCSummaryTree(\n\t\tserializedGCState: string,\n\t\tserializedTombstones: string | undefined,\n\t\tserializedDeletedNodes: string | undefined,\n\t\ttrackState: boolean,\n\t): ISummaryTreeWithStats {\n\t\tconst builder = new SummaryTreeBuilder();\n\n\t\t// If the GC state hasn't changed, write a summary handle, else write a summary blob for it.\n\t\tif (this.latestSummaryData?.serializedGCState === serializedGCState && trackState) {\n\t\t\tbuilder.addHandle(gcStateBlobKey, SummaryType.Blob, `/${gcTreeKey}/${gcStateBlobKey}`);\n\t\t} else {\n\t\t\tbuilder.addBlob(gcStateBlobKey, serializedGCState);\n\t\t}\n\n\t\t// If tombstones exist, write a summary handle if it hasn't changed. If it has changed, write a\n\t\t// summary blob.\n\t\tif (serializedTombstones !== undefined) {\n\t\t\tif (\n\t\t\t\tthis.latestSummaryData?.serializedTombstones === serializedTombstones &&\n\t\t\t\ttrackState\n\t\t\t) {\n\t\t\t\tbuilder.addHandle(\n\t\t\t\t\tgcTombstoneBlobKey,\n\t\t\t\t\tSummaryType.Blob,\n\t\t\t\t\t`/${gcTreeKey}/${gcTombstoneBlobKey}`,\n\t\t\t\t);\n\t\t\t} else {\n\t\t\t\tbuilder.addBlob(gcTombstoneBlobKey, serializedTombstones);\n\t\t\t}\n\t\t}\n\n\t\t// If there are no deleted nodes, return the summary tree.\n\t\tif (serializedDeletedNodes === undefined) {\n\t\t\treturn builder.getSummaryTree();\n\t\t}\n\n\t\t// If the deleted nodes hasn't changed, write a summary handle, else write a summary blob for it.\n\t\tif (\n\t\t\tthis.latestSummaryData?.serializedDeletedNodes === serializedDeletedNodes &&\n\t\t\ttrackState\n\t\t) {\n\t\t\tbuilder.addHandle(\n\t\t\t\tgcDeletedBlobKey,\n\t\t\t\tSummaryType.Blob,\n\t\t\t\t`/${gcTreeKey}/${gcDeletedBlobKey}`,\n\t\t\t);\n\t\t} else {\n\t\t\tbuilder.addBlob(gcDeletedBlobKey, serializedDeletedNodes);\n\t\t}\n\t\treturn builder.getSummaryTree();\n\t}\n\n\t/**\n\t * Called to refresh the latest summary state. This happens when either a pending summary is acked.\n\t */\n\tpublic async refreshLatestSummary(result: IRefreshSummaryResult): Promise<void> {\n\t\tif (!result.isSummaryTracked) {\n\t\t\treturn;\n\t\t}\n\n\t\t// If the summary is tracked, this client is the one that generated it. So, update wasGCRunInLatestSummary.\n\t\t// Note that this has to be updated if GC did not run too. Otherwise, `gcStateNeedsReset` will always return\n\t\t// true in scenarios where GC is currently disabled but enabled in the snapshot we loaded from.\n\t\tthis.wasGCRunInLatestSummary = this.configs.shouldRunGC;\n\n\t\tif (!this.configs.shouldRunGC) {\n\t\t\treturn;\n\t\t}\n\n\t\tthis.latestSummaryGCVersion = this.configs.gcVersionInEffect;\n\t\tthis.latestSummaryData = this.pendingSummaryData;\n\t\tthis.pendingSummaryData = undefined;\n\t\tthis.updatedDSCountSinceLastSummary = 0;\n\t\treturn;\n\t}\n\n\t/**\n\t * Called to update the state from a GC run's stats. Used to update the count of data stores whose state updated.\n\t */\n\tpublic updateStateFromGCRunStats(stats: IGCStats) {\n\t\tthis.updatedDSCountSinceLastSummary += stats.updatedDataStoreCount;\n\t}\n}\n"]}

package/lib/gc/gcTelemetry.d.mts

@@ -0,0 +1,92 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ITelemetryGenericEvent } from "@fluidframework/core-interfaces";
+import { IGarbageCollectionData } from "@fluidframework/runtime-definitions";
+import { ITelemetryLoggerExt, MonitoringContext } from "@fluidframework/telemetry-utils";
+import { RuntimeHeaderData } from "../containerRuntime.mjs";
+import { ICreateContainerMetadata } from "../summary/index.mjs";
+import { GCNodeType, IGarbageCollectorConfigs } from "./gcDefinitions.mjs";
+import { UnreferencedStateTracker } from "./gcUnreferencedStateTracker.mjs";
+type NodeUsageType = "Changed" | "Loaded" | "Revived";
+/** Properties that are common to IUnreferencedEventProps and INodeUsageProps */
+interface ICommonProps {
+    usageType: NodeUsageType;
+    completedGCRuns: number;
+    isTombstoned: boolean;
+    lastSummaryTime?: number;
+    headers?: RuntimeHeaderData;
+}
+/** Properties passed to nodeUsed function when a node is used. */
+interface INodeUsageProps extends ICommonProps {
+    id: string;
+    currentReferenceTimestampMs: number | undefined;
+    packagePath: readonly string[] | undefined;
+    fromId?: string;
+}
+/**
+ * Encapsulates the logic that tracks the various telemetry logged by the Garbage Collector. There are 4 types of
+ * telemetry logged:
+ * 1. inactiveObject telemetry - When an inactive node is used - A node that has been unreferenced for inactiveTimeoutMs.
+ * 2. sweepReadyObject telemetry - When a sweep ready node is used - A node that has been unreferenced for sweepTimeoutMs.
+ * 3. Tombstone telemetry - When a tombstoned node is used - A node that that has been marked as tombstone.
+ * 4. Sweep / deleted telemetry - When a node is detected as sweep ready in the sweep phase.
+ * 5. Unknown outbound reference telemetry - When a node is referenced but GC is not explicitly notified of it.
+ */
+export declare class GCTelemetryTracker {
+    private readonly mc;
+    private readonly configs;
+    private readonly isSummarizerClient;
+    private readonly createContainerMetadata;
+    private readonly getNodeType;
+    private readonly getNodeStateTracker;
+    private readonly getNodePackagePath;
+    private readonly loggedUnreferencedEvents;
+    private pendingEventsQueue;
+    constructor(mc: MonitoringContext, configs: IGarbageCollectorConfigs, isSummarizerClient: boolean, createContainerMetadata: ICreateContainerMetadata, getNodeType: (nodeId: string) => GCNodeType, getNodeStateTracker: (nodeId: string) => UnreferencedStateTracker | undefined, getNodePackagePath: (nodePath: string) => Promise<readonly string[] | undefined>);
+    /**
+     * Returns whether an event should be logged for a node that isn't active anymore. This does not apply to
+     * tombstoned nodes for which an event is always logged. Some scenarios where we won't log:
+     * 1. When a DDS is changed. The corresponding data store's event will be logged instead.
+     * 2. An event is logged only once per container instance per event per node.
+     */
+    private shouldLogNonActiveEvent;
+    /**
+     * Called when a node is used. If the node is not active or tombstoned, log telemetry indicating object is used
+     * when it should not have been.
+     */
+    nodeUsed(nodeUsageProps: INodeUsageProps): void;
+    /**
+     * Logs telemetry when a tombstoned object is changed, revived or loaded.
+     */
+    private logTombstoneUsageTelemetry;
+    /**
+     * Log all new references or outbound routes in the current graph that haven't been explicitly notified to GC.
+     * The principle is that every new reference or outbound route must be notified to GC via the
+     * addedOutboundReference method. It it hasn't, its a bug and we want to identify these scenarios.
+     *
+     * In more simple terms:
+     * Missing Explicit References = Current References - Previous References - Explicitly Added References;
+     *
+     * @param currentGCData - The GC data (reference graph) from the current GC run.
+     * @param previousGCData - The GC data (reference graph) from the previous GC run.
+     * @param explicitReferences - New references added explicity between the previous and the current run.
+     */
+    logIfMissingExplicitReferences(currentGCData: IGarbageCollectionData, previousGCData: IGarbageCollectionData, explicitReferences: Map<string, string[]>, logger: ITelemetryLoggerExt): void;
+    /**
+     * Log events that are pending in pendingEventsQueue. This is called after GC runs in the summarizer client
+     * so that the state of an unreferenced node is updated.
+     */
+    logPendingEvents(logger: ITelemetryLoggerExt): Promise<void>;
+}
+/**
+ * Consolidates info / logic for logging when we encounter unexpected usage of GC'd objects. For example, when a
+ * tombstoned or deleted object is loaded.
+ */
+export declare function sendGCUnexpectedUsageEvent(mc: MonitoringContext, event: ITelemetryGenericEvent & {
+    category: "error" | "generic";
+    gcTombstoneEnforcementAllowed: boolean | undefined;
+}, packagePath: readonly string[] | undefined, error?: unknown): void;
+export {};
+//# sourceMappingURL=gcTelemetry.d.ts.map

package/lib/gc/gcTelemetry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcTelemetry.d.ts","sourceRoot":"","sources":["../../src/gc/gcTelemetry.ts"],"names":[],"mappings":"AAAA;;;GAGG;OAEI,EAAE,sBAAsB,EAAE,MAAM,iCAAiC;OACjE,EAAE,sBAAsB,EAAE,MAAM,qCAAqC;OACrE,EAEN,mBAAmB,EACnB,iBAAiB,EAEjB,MAAM,iCAAiC;OACjC,EAAE,iBAAiB,EAAE;OACrB,EAAE,wBAAwB,EAAE;OAC5B,EACN,UAAU,EAEV,wBAAwB,EAMxB;OACM,EAAE,wBAAwB,EAAE;AAEnC,KAAK,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEtD,gFAAgF;AAChF,UAAU,YAAY;IACrB,SAAS,EAAE,aAAa,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAuBD,kEAAkE;AAClE,UAAU,eAAgB,SAAQ,YAAY;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAQ7B,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,uBAAuB;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IAGpC,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAbpC,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAA0B;IAEnE,OAAO,CAAC,kBAAkB,CAAiC;gBAGzC,EAAE,EAAE,iBAAiB,EACrB,OAAO,EAAE,wBAAwB,EACjC,kBAAkB,EAAE,OAAO,EAC3B,uBAAuB,EAAE,wBAAwB,EACjD,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,EAC3C,mBAAmB,EAAE,CACrC,MAAM,EAAE,MAAM,KACV,wBAAwB,GAAG,SAAS,EACxB,kBAAkB,EAAE,CACpC,QAAQ,EAAE,MAAM,KACZ,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAG5C;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IA4B/B;;;OAGG;IACI,QAAQ,CAAC,cAAc,EAAE,eAAe;IAkH/C;;OAEG;IACH,OAAO,CAAC,0BAA0B;IA2ClC;;;;;;;;;;;OAWG;IACI,8BAA8B,CACpC,aAAa,EAAE,sBAAsB,EACrC,cAAc,EAAE,sBAAsB,EACtC,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EACzC,MAAM,EAAE,mBAAmB;IAuC5B;;;OAGG;IACU,gBAAgB,CAAC,MAAM,EAAE,mBAAmB;CA0CzD;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACzC,EAAE,EAAE,iBAAiB,EACrB,KAAK,EAAE,sBAAsB,GAAG;IAC/B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,6BAA6B,EAAE,OAAO,GAAG,SAAS,CAAC;CACnD,EACD,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAC1C,KAAK,CAAC,EAAE,OAAO,QAaf"}

package/lib/gc/gcTelemetry.mjs

@@ -0,0 +1,293 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { generateStack, tagCodeArtifacts, } from "@fluidframework/telemetry-utils";
+import { GCNodeType, UnreferencedState, disableTombstoneKey, throwOnTombstoneUsageKey, throwOnTombstoneLoadOverrideKey, runSweepKey, } from "./gcDefinitions.mjs";
+/**
+ * Encapsulates the logic that tracks the various telemetry logged by the Garbage Collector. There are 4 types of
+ * telemetry logged:
+ * 1. inactiveObject telemetry - When an inactive node is used - A node that has been unreferenced for inactiveTimeoutMs.
+ * 2. sweepReadyObject telemetry - When a sweep ready node is used - A node that has been unreferenced for sweepTimeoutMs.
+ * 3. Tombstone telemetry - When a tombstoned node is used - A node that that has been marked as tombstone.
+ * 4. Sweep / deleted telemetry - When a node is detected as sweep ready in the sweep phase.
+ * 5. Unknown outbound reference telemetry - When a node is referenced but GC is not explicitly notified of it.
+ */
+export class GCTelemetryTracker {
+    constructor(mc, configs, isSummarizerClient, createContainerMetadata, getNodeType, getNodeStateTracker, getNodePackagePath) {
+        this.mc = mc;
+        this.configs = configs;
+        this.isSummarizerClient = isSummarizerClient;
+        this.createContainerMetadata = createContainerMetadata;
+        this.getNodeType = getNodeType;
+        this.getNodeStateTracker = getNodeStateTracker;
+        this.getNodePackagePath = getNodePackagePath;
+        // Keeps track of unreferenced events that are logged for a node. This is used to limit the log generation to one
+        // per event per node.
+        this.loggedUnreferencedEvents = new Set();
+        // Queue for unreferenced events that should be logged the next time GC runs.
+        this.pendingEventsQueue = [];
+    }
+    /**
+     * Returns whether an event should be logged for a node that isn't active anymore. This does not apply to
+     * tombstoned nodes for which an event is always logged. Some scenarios where we won't log:
+     * 1. When a DDS is changed. The corresponding data store's event will be logged instead.
+     * 2. An event is logged only once per container instance per event per node.
+     */
+    shouldLogNonActiveEvent(nodeType, usageType, nodeStateTracker, uniqueEventId) {
+        if (nodeStateTracker.state === UnreferencedState.Active) {
+            return false;
+        }
+        if (nodeType === GCNodeType.Other) {
+            return false;
+        }
+        // For sub data store (DDS) nodes, if they are changed, its data store will also be changed,
+        // so skip logging to make the telemetry less noisy.
+        if (nodeType === GCNodeType.SubDataStore && usageType === "Changed") {
+            return false;
+        }
+        // Non-tombstone events are logged once per event per node. A unique id is generated by joining
+        // node state (inactive / sweep ready), node's id and usage (loaded / changed / revived).
+        if (this.loggedUnreferencedEvents.has(uniqueEventId)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Called when a node is used. If the node is not active or tombstoned, log telemetry indicating object is used
+     * when it should not have been.
+     */
+    nodeUsed(nodeUsageProps) {
+        // If there is no reference timestamp to work with, no ops have been processed after creation. If so, skip
+        // logging as nothing interesting would have happened worth logging.
+        if (nodeUsageProps.currentReferenceTimestampMs === undefined) {
+            return;
+        }
+        const nodeStateTracker = this.getNodeStateTracker(nodeUsageProps.id);
+        const nodeType = this.getNodeType(nodeUsageProps.id);
+        const timeout = (() => {
+            switch (nodeStateTracker?.state) {
+                case UnreferencedState.Inactive:
+                    return this.configs.inactiveTimeoutMs;
+                case UnreferencedState.TombstoneReady:
+                    return this.configs.sweepTimeoutMs;
+                case UnreferencedState.SweepReady:
+                    return (this.configs.sweepTimeoutMs &&
+                        this.configs.sweepTimeoutMs + this.configs.sweepGracePeriodMs);
+                default:
+                    return undefined;
+            }
+        })();
+        const { usageType, currentReferenceTimestampMs, packagePath, id: untaggedId, fromId: untaggedFromId, ...propsToLog } = nodeUsageProps;
+        const { persistedGcFeatureMatrix, ...configs } = this.configs;
+        const unrefEventProps = {
+            type: nodeType,
+            unrefTime: nodeStateTracker?.unreferencedTimestampMs ?? -1,
+            age: nodeStateTracker !== undefined
+                ? nodeUsageProps.currentReferenceTimestampMs -
+                    nodeStateTracker.unreferencedTimestampMs
+                : -1,
+            timeout,
+            ...tagCodeArtifacts({ id: untaggedId, fromId: untaggedFromId }),
+            ...propsToLog,
+            ...this.createContainerMetadata,
+            gcConfigs: { ...configs, ...persistedGcFeatureMatrix },
+        };
+        // If the node that is used is tombstoned, log a tombstone telemetry.
+        // Note that this is done before checking if "nodeStateTracker" is undefined below because unreferenced
+        // tracking may not have yet been enabled. That happens only after the client transitions to write mode.
+        if (nodeUsageProps.isTombstoned) {
+            this.logTombstoneUsageTelemetry(nodeUsageProps, unrefEventProps, nodeType, usageType);
+        }
+        // After logging tombstone telemetry, if the node's unreferenced state is not tracked, there is nothing
+        // else to log.
+        if (nodeStateTracker === undefined) {
+            return;
+        }
+        const state = nodeStateTracker.state;
+        const uniqueEventId = `${state}-${nodeUsageProps.id}-${nodeUsageProps.usageType}`;
+        if (!this.shouldLogNonActiveEvent(nodeType, nodeUsageProps.usageType, nodeStateTracker, uniqueEventId)) {
+            return;
+        }
+        // Add the unique event id so that we don't generate a log for this event again in this session.
+        this.loggedUnreferencedEvents.add(uniqueEventId);
+        // For summarizer client, queue the event so it is logged the next time GC runs if the event is still valid.
+        // For non-summarizer client, log the event now since GC won't run on it. This may result in false positives
+        // but it's a good signal nonetheless and we can consume it with a grain of salt.
+        // Inactive errors are usages of Objects that are unreferenced for at least a period of 7 days.
+        // SweepReady errors are usages of Objects that will be deleted by GC Sweep!
+        if (this.isSummarizerClient) {
+            this.pendingEventsQueue.push({
+                ...unrefEventProps,
+                usageType: nodeUsageProps.usageType,
+                state,
+            });
+        }
+        else {
+            // For non-summarizer clients, only log "Loaded" type events since these objects may not be loaded in the
+            // summarizer clients if they are based off of user actions (such as scrolling to content for these objects)
+            // Events generated:
+            // InactiveObject_Loaded, SweepReadyObject_Loaded
+            if (nodeUsageProps.usageType === "Loaded") {
+                const { id, fromId, headers, gcConfigs, ...detailedProps } = unrefEventProps;
+                const event = {
+                    eventName: `${state}Object_${nodeUsageProps.usageType}`,
+                    ...tagCodeArtifacts({ pkg: nodeUsageProps.packagePath?.join("/") }),
+                    stack: generateStack(),
+                    id,
+                    fromId,
+                    headers: { ...headers },
+                    details: detailedProps,
+                    gcConfigs,
+                };
+                // These are logged as generic events and not errors because there can be false positives. The Tombstone
+                // and Delete errors are separately logged and are reliable.
+                this.mc.logger.sendTelemetryEvent(event);
+            }
+        }
+    }
+    /**
+     * Logs telemetry when a tombstoned object is changed, revived or loaded.
+     */
+    logTombstoneUsageTelemetry(nodeUsageProps, unrefEventProps, nodeType, usageType) {
+        // This will log the following events:
+        // GC_Tombstone_DataStore_Requested, GC_Tombstone_DataStore_Changed, GC_Tombstone_DataStore_Revived
+        // GC_Tombstone_SubDataStore_Requested, GC_Tombstone_SubDataStore_Changed, GC_Tombstone_SubDataStore_Revived
+        // GC_Tombstone_Blob_Requested, GC_Tombstone_Blob_Changed, GC_Tombstone_Blob_Revived
+        const { id, fromId, headers, gcConfigs, ...detailedProps } = unrefEventProps;
+        const eventUsageName = usageType === "Loaded" ? "Requested" : usageType;
+        const event = {
+            eventName: `GC_Tombstone_${nodeType}_${eventUsageName}`,
+            pkg: tagCodeArtifacts({ pkg: nodeUsageProps.packagePath?.join("/") }).pkg,
+            stack: generateStack(),
+            id,
+            fromId,
+            headers: { ...headers },
+            details: detailedProps,
+            gcConfigs,
+            tombstoneFlags: {
+                DisableTombstone: this.mc.config.getBoolean(disableTombstoneKey),
+                ThrowOnTombstoneUsage: this.mc.config.getBoolean(throwOnTombstoneUsageKey),
+                ThrowOnTombstoneLoad: this.mc.config.getBoolean(throwOnTombstoneLoadOverrideKey),
+            },
+            sweepFlags: {
+                EnableSweepFlag: this.mc.config.getBoolean(runSweepKey),
+            },
+        };
+        if ((usageType === "Loaded" &&
+            this.configs.throwOnTombstoneLoad &&
+            !headers?.allowTombstone) ||
+            (usageType === "Changed" && this.configs.throwOnTombstoneUsage)) {
+            this.mc.logger.sendErrorEvent(event);
+        }
+        else {
+            this.mc.logger.sendTelemetryEvent(event);
+        }
+    }
+    /**
+     * Log all new references or outbound routes in the current graph that haven't been explicitly notified to GC.
+     * The principle is that every new reference or outbound route must be notified to GC via the
+     * addedOutboundReference method. It it hasn't, its a bug and we want to identify these scenarios.
+     *
+     * In more simple terms:
+     * Missing Explicit References = Current References - Previous References - Explicitly Added References;
+     *
+     * @param currentGCData - The GC data (reference graph) from the current GC run.
+     * @param previousGCData - The GC data (reference graph) from the previous GC run.
+     * @param explicitReferences - New references added explicity between the previous and the current run.
+     */
+    logIfMissingExplicitReferences(currentGCData, previousGCData, explicitReferences, logger) {
+        for (const [nodeId, currentOutboundRoutes] of Object.entries(currentGCData.gcNodes)) {
+            const previousRoutes = previousGCData.gcNodes[nodeId] ?? [];
+            const explicitRoutes = explicitReferences.get(nodeId) ?? [];
+            /**
+             * 1. For routes in the current GC data, routes that were not present in previous GC data and did not have
+             * explicit references should be added to missing explicit routes list.
+             * 2. Only include data store and blob routes since GC only works for these two.
+             * Note: Due to a bug with de-duped blobs, only adding data store routes for now.
+             * 3. Ignore DDS routes to their parent datastores since those were added implicitly. So, there won't be
+             * explicit routes to them.
+             */
+            const missingExplicitRoutes = [];
+            for (const route of currentOutboundRoutes) {
+                const nodeType = this.getNodeType(route);
+                if ((nodeType === GCNodeType.DataStore || nodeType === GCNodeType.Blob) &&
+                    !nodeId.startsWith(route) &&
+                    !previousRoutes.includes(route) &&
+                    !explicitRoutes.includes(route)) {
+                    missingExplicitRoutes.push(route);
+                }
+            }
+            if (missingExplicitRoutes.length > 0) {
+                logger.sendErrorEvent({
+                    eventName: "gcUnknownOutboundReferences",
+                    ...tagCodeArtifacts({
+                        id: nodeId,
+                        routes: JSON.stringify(missingExplicitRoutes),
+                    }),
+                });
+            }
+        }
+    }
+    /**
+     * Log events that are pending in pendingEventsQueue. This is called after GC runs in the summarizer client
+     * so that the state of an unreferenced node is updated.
+     */
+    async logPendingEvents(logger) {
+        // Events sent come only from the summarizer client. In between summaries, events are pushed to a queue and at
+        // summary time they are then logged.
+        // Events generated:
+        // InactiveObject_Loaded, InactiveObject_Changed, InactiveObject_Revived
+        // SweepReadyObject_Loaded, SweepReadyObject_Changed, SweepReadyObject_Revived
+        for (const eventProps of this.pendingEventsQueue) {
+            // const { usageType, state, id, fromId, ...propsToLog } = eventProps;
+            const { usageType, state, id, fromId, headers, gcConfigs, ...detailedProps } = eventProps;
+            /**
+             * Revived event is logged only if the node is active. If the node is not active, the reference to it was
+             * from another unreferenced node and this scenario is not interesting to log.
+             * Loaded and Changed events are logged only if the node is not active. If the node is active, it was
+             * revived and a Revived event will be logged for it.
+             */
+            const nodeStateTracker = this.getNodeStateTracker(eventProps.id.value);
+            const active = nodeStateTracker === undefined ||
+                nodeStateTracker.state === UnreferencedState.Active;
+            if ((usageType === "Revived") === active) {
+                const pkg = await this.getNodePackagePath(eventProps.id.value);
+                const fromPkg = eventProps.fromId
+                    ? await this.getNodePackagePath(eventProps.fromId.value)
+                    : undefined;
+                const event = {
+                    eventName: `${state}Object_${usageType}`,
+                    id,
+                    fromId,
+                    headers: { ...headers },
+                    details: detailedProps,
+                    gcConfigs,
+                    ...tagCodeArtifacts({
+                        pkg: pkg?.join("/"),
+                        fromPkg: fromPkg?.join("/"),
+                    }),
+                };
+                logger.sendTelemetryEvent(event);
+            }
+        }
+        this.pendingEventsQueue = [];
+    }
+}
+/**
+ * Consolidates info / logic for logging when we encounter unexpected usage of GC'd objects. For example, when a
+ * tombstoned or deleted object is loaded.
+ */
+export function sendGCUnexpectedUsageEvent(mc, event, packagePath, error) {
+    event.pkg = tagCodeArtifacts({ pkg: packagePath?.join("/") })?.pkg;
+    event.tombstoneFlags = JSON.stringify({
+        DisableTombstone: mc.config.getBoolean(disableTombstoneKey),
+        ThrowOnTombstoneUsage: mc.config.getBoolean(throwOnTombstoneUsageKey),
+        ThrowOnTombstoneLoad: mc.config.getBoolean(throwOnTombstoneLoadOverrideKey),
+    });
+    event.sweepFlags = JSON.stringify({
+        EnableSweepFlag: mc.config.getBoolean(runSweepKey),
+    });
+    mc.logger.sendTelemetryEvent(event, error);
+}
+//# sourceMappingURL=gcTelemetry.mjs.map