@fluidframework/container-runtime 2.23.0 → 2.31.0

package/src/messageTypes.ts

@@ -14,7 +14,6 @@ import {
 import { IDataStoreAliasMessage } from "./dataStore.js";
 import { GarbageCollectionMessage } from "./gc/index.js";
 import { IChunkedOp } from "./opLifecycle/index.js";
-// eslint-disable-next-line import/no-deprecated
 import { IDocumentSchemaChangeMessage } from "./summary/index.js";
 
 /**
@@ -115,7 +114,6 @@ export type ContainerRuntimeGCMessage = TypedContainerRuntimeMessage<
 >;
 export type ContainerRuntimeDocumentSchemaMessage = TypedContainerRuntimeMessage<
 	ContainerMessageType.DocumentSchemaChange,
-	// eslint-disable-next-line import/no-deprecated
 	IDocumentSchemaChangeMessage
 >;
 

package/src/opLifecycle/batchManager.ts

@@ -4,6 +4,11 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
+import {
+	LoggingError,
+	tagData,
+	TelemetryDataTag,
+} from "@fluidframework/telemetry-utils/internal";
 
 import { ICompressionRuntimeOptions } from "../containerRuntime.js";
 import { asBatchMetadata, type IBatchMetadata } from "../metadata.js";
@@ -99,7 +104,8 @@ export class BatchManager {
 	private get referenceSequenceNumber(): number | undefined {
 		return this.pendingBatch.length === 0
 			? undefined
-			: this.pendingBatch[this.pendingBatch.length - 1].referenceSequenceNumber;
+			: // NOTE: In case of reentrant ops, there could be multiple reference sequence numbers, but we will rebase before submitting.
+				this.pendingBatch[this.pendingBatch.length - 1].referenceSequenceNumber;
 	}
 
 	/**
@@ -166,17 +172,25 @@ export class BatchManager {
 	 * Capture the pending state at this point
 	 */
 	public checkpoint(): IBatchCheckpoint {
+		const startSequenceNumber = this.clientSequenceNumber;
 		const startPoint = this.pendingBatch.length;
 		return {
 			rollback: (process: (message: BatchMessage) => void) => {
-				for (let i = this.pendingBatch.length; i > startPoint; ) {
-					i--;
-					const message = this.pendingBatch[i];
+				this.clientSequenceNumber = startSequenceNumber;
+				const rollbackOpsLifo = this.pendingBatch.splice(startPoint).reverse();
+				for (const message of rollbackOpsLifo) {
 					this.batchContentSize -= message.contents?.length ?? 0;
 					process(message);
 				}
-
-				this.pendingBatch.length = startPoint;
+				const count = this.pendingBatch.length - startPoint;
+				if (count !== 0) {
+					throw new LoggingError("Ops generated durning rollback", {
+						count,
+						...tagData(TelemetryDataTag.UserData, {
+							ops: JSON.stringify(this.pendingBatch.slice(startPoint).map((b) => b.contents)),
+						}),
+					});
+				}
 			},
 		};
 	}

package/src/opLifecycle/outbox.ts

@@ -6,8 +6,9 @@
 import { ICriticalContainerError } from "@fluidframework/container-definitions";
 import { IBatchMessage } from "@fluidframework/container-definitions/internal";
 import { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
-import { assert } from "@fluidframework/core-utils/internal";
+import { assert, Lazy } from "@fluidframework/core-utils/internal";
 import {
+	DataProcessingError,
 	GenericError,
 	UsageError,
 	createChildLogger,
@@ -34,9 +35,16 @@ import { ensureContentsDeserialized } from "./remoteMessageProcessor.js";
 
 export interface IOutboxConfig {
 	readonly compressionOptions: ICompressionRuntimeOptions;
-	// The maximum size of a batch that we can send over the wire.
+	/**
+	 * The maximum size of a batch that we can send over the wire.
+	 */
 	readonly maxBatchSizeInBytes: number;
-	readonly disablePartialFlush: boolean;
+	/**
+	 * If true, maybeFlushPartialBatch will flush the batch if the reference sequence number changed
+	 * since the batch started. Otherwise, it will throw in this case (apart from reentrancy which is handled elsewhere).
+	 * Once the new throw-based flow is proved in a production environment, this option will be removed.
+	 */
+	readonly flushPartialBatches: boolean;
 }
 
 export interface IOutboxParameters {
@@ -170,8 +178,9 @@ export class Outbox {
 
 	/**
 	 * Detect whether batching has been interrupted by an incoming message being processed. In this case,
-	 * we will flush the accumulated messages to account for that and create a new batch with the new
-	 * message as the first message.
+	 * we will flush the accumulated messages to account for that (if allowed) and create a new batch with the new
+	 * message as the first message. If flushing partial batch is not enabled, we will throw (except for reentrant ops).
+	 * This would indicate we expected this case to be precluded by logic elsewhere.
 	 *
 	 * @remarks - To detect batch interruption, we compare both the reference sequence number
 	 * (i.e. last message processed by DeltaManager) and the client sequence number of the
@@ -183,9 +192,8 @@ export class Outbox {
 		const blobAttachSeqNums = this.blobAttachBatch.sequenceNumbers;
 		const idAllocSeqNums = this.idAllocationBatch.sequenceNumbers;
 		assert(
-			this.params.config.disablePartialFlush ||
-				(sequenceNumbersMatch(mainBatchSeqNums, blobAttachSeqNums) &&
-					sequenceNumbersMatch(mainBatchSeqNums, idAllocSeqNums)),
+			sequenceNumbersMatch(mainBatchSeqNums, blobAttachSeqNums) &&
+				sequenceNumbersMatch(mainBatchSeqNums, idAllocSeqNums),
 			0x58d /* Reference sequence numbers from both batches must be in sync */,
 		);
 
@@ -200,25 +208,54 @@ export class Outbox {
 			return;
 		}
 
+		// Reference and/or Client sequence number will be advancing while processing this batch,
+		// so we can't use this check to detect wrongdoing. But we will still log via telemetry.
+		// This is rare, and the reentrancy will be handled during Flush.
+		const expectedDueToReentrancy = this.isContextReentrant();
+
+		const errorWrapper = new Lazy(() =>
+			getLongStack(() =>
+				DataProcessingError.create(
+					"Sequence numbers advanced as if ops were processed while a batch is accumulating",
+					"outboxSequenceNumberCoherencyCheck",
+				),
+			),
+		);
 		if (++this.mismatchedOpsReported <= this.maxMismatchedOpsToReport) {
 			this.logger.sendTelemetryEvent(
 				{
-					category: this.params.config.disablePartialFlush ? "error" : "generic",
+					// Only log error if this is truly unexpected
+					category:
+						expectedDueToReentrancy || this.params.config.flushPartialBatches
+							? "generic"
+							: "error",
 					eventName: "ReferenceSequenceNumberMismatch",
-					mainReferenceSequenceNumber: mainBatchSeqNums.referenceSequenceNumber,
-					mainClientSequenceNumber: mainBatchSeqNums.clientSequenceNumber,
-					blobAttachReferenceSequenceNumber: blobAttachSeqNums.referenceSequenceNumber,
-					blobAttachClientSequenceNumber: blobAttachSeqNums.clientSequenceNumber,
-					currentReferenceSequenceNumber: currentSequenceNumbers.referenceSequenceNumber,
-					currentClientSequenceNumber: currentSequenceNumbers.clientSequenceNumber,
+					Data_details: {
+						expectedDueToReentrancy,
+						mainReferenceSequenceNumber: mainBatchSeqNums.referenceSequenceNumber,
+						mainClientSequenceNumber: mainBatchSeqNums.clientSequenceNumber,
+						blobAttachReferenceSequenceNumber: blobAttachSeqNums.referenceSequenceNumber,
+						blobAttachClientSequenceNumber: blobAttachSeqNums.clientSequenceNumber,
+						currentReferenceSequenceNumber: currentSequenceNumbers.referenceSequenceNumber,
+						currentClientSequenceNumber: currentSequenceNumbers.clientSequenceNumber,
+					},
 				},
-				getLongStack(() => new UsageError("Submission of an out of order message")),
+				errorWrapper.value,
 			);
 		}
 
-		if (!this.params.config.disablePartialFlush) {
+		// If we're configured to flush partial batches, do that now and return (don't throw)
+		if (this.params.config.flushPartialBatches) {
 			this.flushAll();
+			return;
 		}
+
+		// If we are in a reentrant context, we know this can happen without causing any harm.
+		if (expectedDueToReentrancy) {
+			return;
+		}
+
+		throw errorWrapper.value;
 	}
 
 	public submit(message: BatchMessage): void {
@@ -273,17 +310,20 @@ export class Outbox {
 	}
 
 	private flushAll(resubmittingBatchId?: BatchId): void {
-		// If we're resubmitting and all batches are empty, we need to flush an empty batch.
-		// Note that we currently resubmit one batch at a time, so on resubmit, 2 of the 3 batches will *always* be empty.
-		// It's theoretically possible that we don't *need* to resubmit this empty batch, and in those cases, it'll safely be ignored
-		// by the rest of the system, including remote clients.
-		// In some cases we *must* resubmit the empty batch (to match up with a non-empty version tracked locally by a container fork), so we do it always.
 		const allBatchesEmpty =
 			this.idAllocationBatch.empty && this.blobAttachBatch.empty && this.mainBatch.empty;
-		if (resubmittingBatchId && allBatchesEmpty) {
-			this.flushEmptyBatch(resubmittingBatchId);
+		if (allBatchesEmpty) {
+			// If we're resubmitting and all batches are empty, we need to flush an empty batch.
+			// Note that we currently resubmit one batch at a time, so on resubmit, 2 of the 3 batches will *always* be empty.
+			// It's theoretically possible that we don't *need* to resubmit this empty batch, and in those cases, it'll safely be ignored
+			// by the rest of the system, including remote clients.
+			// In some cases we *must* resubmit the empty batch (to match up with a non-empty version tracked locally by a container fork), so we do it always.
+			if (resubmittingBatchId) {
+				this.flushEmptyBatch(resubmittingBatchId);
+			}
 			return;
 		}
+
 		// Don't use resubmittingBatchId for idAllocationBatch.
 		// ID Allocation messages are not directly resubmitted so we don't want to reuse the batch ID.
 		this.flushInternal(this.idAllocationBatch);

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-runtime";
-export const pkgVersion = "2.23.0";
+export const pkgVersion = "2.31.0";

package/src/pendingStateManager.ts

@@ -134,7 +134,7 @@ function scrubAndStringify(
 	// Scrub the whole object in case there are unexpected keys
 	const scrubbed: Record<string, unknown> = typesOfKeys(message);
 
-	// For these known/expected keys, we can either drill in (for contents)
+	// For these known/expected keys, we can either drill into the object (for contents)
 	// or just use the value as-is (since it's not personal info)
 	scrubbed.contents = message.contents && typesOfKeys(message.contents);
 	scrubbed.type = message.type;
@@ -145,7 +145,7 @@ function scrubAndStringify(
 /**
  * Finds and returns the index where the strings diverge, and the character at that index in each string (or undefined if not applicable)
  */
-export function findFirstCharacterMismatched(
+function findFirstRawCharacterMismatched(
 	a: string,
 	b: string,
 ): [index: number, charA?: string, charB?: string] {
@@ -164,6 +164,22 @@ export function findFirstCharacterMismatched(
 		: [minLength, a[minLength], b[minLength]];
 }
 
+/**
+ * Finds and returns the index where the strings diverge, and the character at that index in each string (or undefined if not applicable)
+ * It scrubs non-ASCII characters since they convey more meaning (privacy consideration)
+ */
+export function findFirstCharacterMismatched(
+	a: string,
+	b: string,
+): [index: number, charA?: string, charB?: string] {
+	const [index, rawCharA, rawCharB] = findFirstRawCharacterMismatched(a, b);
+
+	const charA = (rawCharA?.codePointAt(0) ?? 0) <= 0x7f ? rawCharA : "[non-ASCII]";
+	const charB = (rawCharB?.codePointAt(0) ?? 0) <= 0x7f ? rawCharB : "[non-ASCII]";
+
+	return [index, charA, charB];
+}
+
 function withoutLocalOpMetadata(message: IPendingMessage): IPendingMessage {
 	return {
 		...message,

package/src/runCounter.ts

@@ -0,0 +1,25 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export class RunCounter {
+	#runs = 0;
+
+	public get running(): boolean {
+		return this.#runs !== 0;
+	}
+
+	public get runs(): number {
+		return this.#runs;
+	}
+
+	public run<T>(act: () => T): T {
+		this.#runs++;
+		try {
+			return act();
+		} finally {
+			this.#runs--;
+		}
+	}
+}

package/src/runtimeLayerCompatState.ts

@@ -0,0 +1,143 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	checkLayerCompatibility,
+	type ILayerCompatDetails,
+	type ILayerCompatSupportRequirements,
+} from "@fluid-internal/client-utils";
+import type { ICriticalContainerError } from "@fluidframework/container-definitions";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+
+import { pkgVersion } from "./packageVersion.js";
+
+/**
+ * The core compatibility details of the Runtime layer that is the same across all layer boundaries.
+ * @internal
+ */
+export const runtimeCoreCompatDetails = {
+	/**
+	 * The package version of the Runtime layer.
+	 */
+	pkgVersion,
+	/**
+	 * The current generation of the Runtime layer.
+	 */
+	generation: 1,
+};
+
+/**
+ * Runtime's compatibility details that is exposed to the Loader layer.
+ * @internal
+ */
+export const runtimeCompatDetailsForLoader: ILayerCompatDetails = {
+	...runtimeCoreCompatDetails,
+	/**
+	 * The features supported by the Runtime layer across the Runtime / Loader boundary.
+	 */
+	supportedFeatures: new Set<string>(),
+};
+
+/**
+ * The requirements that the Loader layer must meet to be compatible with this Runtime.
+ * @internal
+ */
+export const loaderSupportRequirements: ILayerCompatSupportRequirements = {
+	/**
+	 * Minimum generation that Loader must be at to be compatible with Runtime. Note that 0 is used here so
+	 * that Loader layers before the introduction of the layer compatibility enforcement are compatible.
+	 */
+	minSupportedGeneration: 0,
+	/**
+	 * The features that the Loader must support to be compatible with Runtime.
+	 */
+	requiredFeatures: [],
+};
+
+/**
+ * Runtime's compatibility details that is exposed to the DataStore layer.
+ * @internal
+ */
+export const runtimeCompatDetailsForDataStore: ILayerCompatDetails = {
+	...runtimeCoreCompatDetails,
+	/**
+	 * The features supported by the Runtime layer across the Runtime / Loader boundary.
+	 */
+	supportedFeatures: new Set<string>(),
+};
+
+/**
+ * The requirements that the DataStore layer must meet to be compatible with this Runtime.
+ * @internal
+ */
+export const dataStoreSupportRequirements: ILayerCompatSupportRequirements = {
+	/**
+	 * Minimum generation that DataStore must be at to be compatible with Runtime. Note that 0 is used here so
+	 * that DataStore layers before the introduction of the layer compatibility enforcement are compatible.
+	 */
+	minSupportedGeneration: 0,
+	/**
+	 * The features that the DataStore must support to be compatible with Runtime.
+	 */
+	requiredFeatures: [],
+};
+
+/**
+ * Validates that the Loader layer is compatible with this Runtime.
+ * @internal
+ */
+export function validateLoaderCompatibility(
+	maybeloaderCompatDetailsForRuntime: ILayerCompatDetails | undefined,
+	disposeFn: (error?: ICriticalContainerError) => void,
+): void {
+	const layerCheckResult = checkLayerCompatibility(
+		loaderSupportRequirements,
+		maybeloaderCompatDetailsForRuntime,
+	);
+	if (!layerCheckResult.isCompatible) {
+		const error = new UsageError("Runtime is not compatible with Loader", {
+			errorDetails: JSON.stringify({
+				runtimeVersion: runtimeCoreCompatDetails.pkgVersion,
+				loaderVersion: maybeloaderCompatDetailsForRuntime?.pkgVersion,
+				runtimeGeneration: runtimeCoreCompatDetails.generation,
+				loaderGeneration: maybeloaderCompatDetailsForRuntime?.generation,
+				minSupportedGeneration: loaderSupportRequirements.minSupportedGeneration,
+				isGenerationCompatible: layerCheckResult.isGenerationCompatible,
+				unsupportedFeatures: layerCheckResult.unsupportedFeatures,
+			}),
+		});
+		disposeFn(error);
+		throw error;
+	}
+}
+
+/**
+ * Validates that the DataStore layer is compatible with this Runtime.
+ * @internal
+ */
+export function validateDatastoreCompatibility(
+	maybeDataStoreCompatDetails: ILayerCompatDetails | undefined,
+	disposeFn: () => void,
+): void {
+	const layerCheckResult = checkLayerCompatibility(
+		dataStoreSupportRequirements,
+		maybeDataStoreCompatDetails,
+	);
+	if (!layerCheckResult.isCompatible) {
+		const error = new UsageError("Runtime is not compatible with DataStore", {
+			errorDetails: JSON.stringify({
+				runtimeVersion: runtimeCoreCompatDetails.pkgVersion,
+				dataStoreVersion: maybeDataStoreCompatDetails?.pkgVersion,
+				runtimeGeneration: runtimeCoreCompatDetails.generation,
+				dataStoreGeneration: maybeDataStoreCompatDetails?.generation,
+				minSupportedGeneration: dataStoreSupportRequirements.minSupportedGeneration,
+				isGenerationCompatible: layerCheckResult.isGenerationCompatible,
+				unsupportedFeatures: layerCheckResult.unsupportedFeatures,
+			}),
+		});
+		disposeFn();
+		throw error;
+	}
+}

package/src/signalTelemetryProcessing.ts

@@ -0,0 +1,233 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ISignalEnvelope } from "@fluidframework/core-interfaces/internal";
+import type {
+	ITelemetryLoggerExt,
+	TelemetryEventPropertyTypeExt,
+} from "@fluidframework/telemetry-utils/internal";
+
+const defaultTelemetrySignalSampleCount = 100;
+
+/**
+ * Set of stats/values used to keep track of telemetry related to signals.
+ */
+interface ISignalTelemetryTracking {
+	/**
+	 * Accumulates the total number of broadcast signals sent during the current signal latency measurement window.
+	 * This value represents the total number of signals sent since the latency measurement began and is used
+	 * logged in telemetry when the latency measurement completes.
+	 */
+	totalSignalsSentInLatencyWindow: number;
+
+	/**
+	 * Counts the number of broadcast signals sent since the last latency measurement was initiated.
+	 * This counter increments with each broadcast signal sent. When a new latency measurement starts,
+	 * this counter is added to `totalSignalsSentInLatencyWindow` and then reset to zero.
+	 */
+	signalsSentSinceLastLatencyMeasurement: number;
+
+	/**
+	 * Number of signals that were expected but not received.
+	 */
+	signalsLost: number;
+
+	/**
+	 * Number of signals received out of order/non-sequentially.
+	 */
+	signalsOutOfOrder: number;
+
+	/**
+	 * Timestamp before submitting the signal we will trace.
+	 */
+	signalTimestamp: number;
+
+	/**
+	 * Signal we will trace for roundtrip latency.
+	 */
+	roundTripSignalSequenceNumber: number | undefined;
+
+	/**
+	 * Next expected signal sequence number to be received.
+	 */
+	trackingSignalSequenceNumber: number | undefined;
+
+	/**
+	 * Inclusive lower bound of signal monitoring window.
+	 * Used by the logic that checks if signals are received out of order.
+	 */
+	minimumTrackingSignalSequenceNumber: number | undefined;
+}
+
+export class SignalTelemetryManager {
+	private readonly signalTracking: ISignalTelemetryTracking = {
+		totalSignalsSentInLatencyWindow: 0,
+		signalsLost: 0,
+		signalsOutOfOrder: 0,
+		signalsSentSinceLastLatencyMeasurement: 0,
+		signalTimestamp: 0,
+		roundTripSignalSequenceNumber: undefined,
+		trackingSignalSequenceNumber: undefined,
+		minimumTrackingSignalSequenceNumber: undefined,
+	};
+
+	/**
+	 * Identifier to track broadcast signals being submitted in order to
+	 * allow collection of data around the roundtrip of signal messages.
+	 */
+	private broadcastSignalSequenceNumber: number = 0;
+
+	/**
+	 * Resets the signal tracking state in the {@link SignalTelemetryManager}.
+	 */
+	public resetTracking(): void {
+		this.signalTracking.signalsLost = 0;
+		this.signalTracking.signalsOutOfOrder = 0;
+		this.signalTracking.signalTimestamp = 0;
+		this.signalTracking.signalsSentSinceLastLatencyMeasurement = 0;
+		this.signalTracking.totalSignalsSentInLatencyWindow = 0;
+		this.signalTracking.roundTripSignalSequenceNumber = undefined;
+		this.signalTracking.trackingSignalSequenceNumber = undefined;
+		this.signalTracking.minimumTrackingSignalSequenceNumber = undefined;
+	}
+
+	/**
+	 * Perform telemetry-related processing of incoming signals.
+	 * @param envelope - The signal envelope to process.
+	 * @param logger - The telemetry logger to use for emitting telemetry events.
+	 * @param consecutiveReconnects - The number of consecutive reconnects that have occurred. Only used for logging.
+	 */
+	public trackReceivedSignal(
+		envelope: ISignalEnvelope,
+		logger: ITelemetryLoggerExt,
+		consecutiveReconnects: number,
+	): void {
+		const {
+			clientBroadcastSignalSequenceNumber,
+			contents: envelopeContents,
+			address: envelopeAddress,
+		} = envelope;
+
+		if (clientBroadcastSignalSequenceNumber === undefined) {
+			return undefined;
+		}
+
+		// If no tracking window has been set, nothing to do
+		if (
+			this.signalTracking.trackingSignalSequenceNumber === undefined ||
+			this.signalTracking.minimumTrackingSignalSequenceNumber === undefined
+		) {
+			return undefined;
+		}
+
+		if (
+			clientBroadcastSignalSequenceNumber >= this.signalTracking.trackingSignalSequenceNumber
+		) {
+			// Calculate the number of signals lost and log the event.
+			const signalsLost =
+				clientBroadcastSignalSequenceNumber - this.signalTracking.trackingSignalSequenceNumber;
+			if (signalsLost > 0) {
+				this.signalTracking.signalsLost += signalsLost;
+				logger.sendErrorEvent({
+					eventName: "SignalLost",
+					details: {
+						signalsLost, // Number of lost signals detected.
+						expectedSequenceNumber: this.signalTracking.trackingSignalSequenceNumber, // The next expected signal sequence number.
+						clientBroadcastSignalSequenceNumber, // Actual signal sequence number received.
+					},
+				});
+			}
+			// Update the tracking signal sequence number to the next expected signal in the sequence.
+			this.signalTracking.trackingSignalSequenceNumber =
+				clientBroadcastSignalSequenceNumber + 1;
+		} else if (
+			// Check if this is a signal in range of interest.
+			clientBroadcastSignalSequenceNumber >=
+			this.signalTracking.minimumTrackingSignalSequenceNumber
+		) {
+			this.signalTracking.signalsOutOfOrder++;
+			const details: TelemetryEventPropertyTypeExt = {
+				expectedSequenceNumber: this.signalTracking.trackingSignalSequenceNumber, // The next expected signal sequence number.
+				clientBroadcastSignalSequenceNumber, // Sequence number of the out of order signal.
+			};
+			// Only log `contents.type` when address is for container to avoid chance that contents type is customer data.
+			if (envelopeAddress === undefined) {
+				details.contentsType = envelopeContents.type; // Type of signal that was received out of order.
+			}
+			logger.sendTelemetryEvent({
+				eventName: "SignalOutOfOrder",
+				details,
+			});
+		}
+
+		if (
+			this.signalTracking.roundTripSignalSequenceNumber !== undefined &&
+			clientBroadcastSignalSequenceNumber >= this.signalTracking.roundTripSignalSequenceNumber
+		) {
+			if (
+				clientBroadcastSignalSequenceNumber ===
+				this.signalTracking.roundTripSignalSequenceNumber
+			) {
+				// Latency tracked signal has been received.
+				// We now emit telemetry with the roundtrip duration of the tracked signal.
+				// The telemetry event also includes metrics for broadcast signals (sent, lost, and out of order),
+				// and these metrics are reset after emitting the event.
+				const duration = Date.now() - this.signalTracking.signalTimestamp;
+				logger.sendPerformanceEvent({
+					eventName: "SignalLatency",
+					details: {
+						duration, // Roundtrip duration of the tracked signal in milliseconds.
+						sent: this.signalTracking.totalSignalsSentInLatencyWindow, // Signals sent since the last logged SignalLatency event.
+						lost: this.signalTracking.signalsLost, // Signals lost since the last logged SignalLatency event.
+						outOfOrder: this.signalTracking.signalsOutOfOrder, // Out of order signals since the last logged SignalLatency event.
+						reconnectCount: consecutiveReconnects, // Container reconnect count.
+					},
+				});
+				this.signalTracking.signalsLost = 0;
+				this.signalTracking.signalsOutOfOrder = 0;
+				this.signalTracking.signalTimestamp = 0;
+				this.signalTracking.totalSignalsSentInLatencyWindow = 0;
+			}
+			this.signalTracking.roundTripSignalSequenceNumber = undefined;
+		}
+	}
+
+	/**
+	 * Updates tracking state for broadcast signals based on the provided signal envelope, and updates the
+	 * envelope with additional information that the signal needs to have stamped on it.
+	 * @remarks Do not call this for non-broadcast signals.
+	 * @param envelope - The signal envelope to process.
+	 */
+	public applyTrackingToBroadcastSignalEnvelope(envelope: ISignalEnvelope): void {
+		const broadcastSignalSequenceNumber = ++this.broadcastSignalSequenceNumber;
+
+		// Stamp with the broadcast signal sequence number.
+		envelope.clientBroadcastSignalSequenceNumber = broadcastSignalSequenceNumber;
+
+		this.signalTracking.signalsSentSinceLastLatencyMeasurement++;
+
+		// If we don't have a signal monitoring window yet,
+		// initialize tracking to expect the next signal sent by the connected client.
+		if (
+			this.signalTracking.minimumTrackingSignalSequenceNumber === undefined ||
+			this.signalTracking.trackingSignalSequenceNumber === undefined
+		) {
+			this.signalTracking.minimumTrackingSignalSequenceNumber = broadcastSignalSequenceNumber;
+			this.signalTracking.trackingSignalSequenceNumber = broadcastSignalSequenceNumber;
+		}
+
+		// Start tracking roundtrip for a new signal only if we are not tracking one already (and sampling logic is met)
+		if (
+			this.signalTracking.roundTripSignalSequenceNumber === undefined &&
+			broadcastSignalSequenceNumber % defaultTelemetrySignalSampleCount === 1
+		) {
+			this.signalTracking.signalTimestamp = Date.now();
+			this.signalTracking.roundTripSignalSequenceNumber = broadcastSignalSequenceNumber;
+			this.signalTracking.totalSignalsSentInLatencyWindow +=
+				this.signalTracking.signalsSentSinceLastLatencyMeasurement;
+			this.signalTracking.signalsSentSinceLastLatencyMeasurement = 0;
+		}
+	}
+}