@fluid-experimental/tree 0.58.2001 → 0.59.1000-61898

package/src/MergeHealth.ts

@@ -0,0 +1,447 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ITelemetryLogger } from '@fluidframework/common-definitions';
+import { assertNotUndefined, fail } from './Common';
+import { PlaceValidationResult, RangeValidationResultKind } from './EditUtilities';
+import { SharedTreeEvent } from './EventTypes';
+import { EditStatus } from './persisted-types';
+import { SequencedEditAppliedEventArguments, SharedTree } from './SharedTree';
+import { TransactionInternal } from './TransactionInternal';
+
+/**
+ * Logs generic telemetry for failed sequenced edits.
+ * Only failing edits that were originally made locally are logged.
+ * @param tree - The tree for which to log the telemetry.
+ */
+export function useFailedSequencedEditTelemetry(tree: SharedTree): { disable: () => void } {
+	function onEdit({ wasLocal, logger, outcome }: SequencedEditAppliedEventArguments): void {
+		if (wasLocal && outcome.status !== EditStatus.Applied) {
+			logger.send({
+				category: 'generic',
+				eventName:
+					outcome.status === EditStatus.Malformed ? 'MalformedSharedTreeEdit' : 'InvalidSharedTreeEdit',
+			});
+		}
+	}
+	tree.on(SharedTreeEvent.SequencedEditApplied, onEdit);
+	return {
+		disable: () => {
+			tree.off(SharedTreeEvent.SequencedEditApplied, onEdit);
+		},
+	};
+}
+
+/**
+ * Statistics about the health of collaborative edit merging when using {@link SharedTree}.
+ * All of those numbers constitute a tally since the last heartbeat was logged or cleared.
+ */
+export interface MergeHealthStats {
+	/** Number of sequenced edits applied (failed or not). */
+	editCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply.
+	 * Such cases are also counted under {@link MergeHealthStats.editCount}.
+	 *
+	 * If this number is greater than the sum of:
+	 * * {@link MergeHealthStats.badPlaceCount}
+	 * * {@link MergeHealthStats.badRangeCount}
+	 * * {@link MergeHealthStats.constraintViolationCount}
+	 * * {@link MergeHealthStats.idAlreadyInUseCount}
+	 * * {@link MergeHealthStats.unknownIdCount}
+	 * * {@link MergeHealthStats.malformedEditCount}
+	 *
+	 * then some failure scenarios are not being tracked adequately.
+	 */
+	failedEditCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a bad place.
+	 * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+	 *
+	 * If this number is greater than the sum of:
+	 * * {@link MergeHealthStats.deletedAncestorBadPlaceCount}
+	 * * {@link MergeHealthStats.deletedSiblingBadPlaceCount}
+	 *
+	 * then some failure scenarios are not being tracked adequately.
+	 */
+	badPlaceCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a bad range.
+	 * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+	 *
+	 * If this number is greater than the sum of:
+	 * * {@link MergeHealthStats.deletedAncestorBadRangeCount}
+	 * * {@link MergeHealthStats.deletedSiblingBadRangeCount}
+	 * * {@link MergeHealthStats.updatedRangeInvertedCount}
+	 * * {@link MergeHealthStats.updatedRangeHasPlacesInDifferentTraitsCount}
+	 * * {@link MergeHealthStats.updatedRangeBadPlaceCount}
+	 * * {@link MergeHealthStats.updatedRangeNeverValidPlaceCount}
+	 *
+	 * then some failure scenarios are not being tracked adequately.
+	 */
+	badRangeCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a place whose ancestors had been concurrently deleted.
+	 * Such cases are also counted under {@link MergeHealthStats.badPlaceCount}.
+	 */
+	deletedAncestorBadPlaceCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a range whose ancestors had been concurrently deleted.
+	 * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+	 */
+	deletedAncestorBadRangeCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a place whose sibling (but not its parent) had been concurrently deleted.
+	 * Such cases are also counted under {@link MergeHealthStats.badPlaceCount}.
+	 */
+	deletedSiblingBadPlaceCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a range whose delimiting sibling(s) (but not its parent) had been concurrently
+	 * deleted.
+	 * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+	 */
+	deletedSiblingBadRangeCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a range whose places were resolvable but inverted (i.e., end before start).
+	 * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+	 */
+	updatedRangeInvertedCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a range whose places were resolvable but in different traits.
+	 * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+	 */
+	updatedRangeHasPlacesInDifferentTraitsCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a range whose places were resolvable but bad.
+	 * This should not happen because place resolution is expected to either return a valid place or fail.
+	 * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+	 */
+	updatedRangeBadPlaceCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a range whose places were not resolvable due to not being valid for any state.
+	 * Such cases are also counted under {@link MergeHealthStats.badRangeCount}.
+	 */
+	updatedRangeNeverValidPlaceCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a constraint violation.
+	 * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+	 *
+	 * If this number is greater than the sum of:
+	 * * {@link MergeHealthStats.rangeConstraintViolationCount}
+	 * * {@link MergeHealthStats.lengthConstraintViolationCount}
+	 * * {@link MergeHealthStats.parentConstraintViolationCount}
+	 * * {@link MergeHealthStats.labelConstraintViolationCount}
+	 *
+	 * then some failure scenarios are not being tracked adequately.
+	 */
+	constraintViolationCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a constrained range becoming invalid or malformed.
+	 * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.
+	 */
+	rangeConstraintViolationCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a constrained range having a different length.
+	 * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.
+	 */
+	lengthConstraintViolationCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a constrained range being under a different parent.
+	 * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.
+	 */
+	parentConstraintViolationCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to a constrained range being under a different label.
+	 * Such cases are also counted under {@link MergeHealthStats.constraintViolationCount}.
+	 */
+	labelConstraintViolationCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to an ID collision.
+	 * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+	 */
+	idAlreadyInUseCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to an ID being unknown.
+	 * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+	 */
+	unknownIdCount: number;
+
+	/**
+	 * Number of sequenced edits that failed to apply due to an edit becoming malformed.
+	 * This should theoretically never happen.
+	 * Such cases are also counted under {@link MergeHealthStats.failedEditCount}.
+	 */
+	malformedEditCount: number;
+
+	/**
+	 * The counts of occurrences for a given path length. `pathLengths[1] === 2` means two occurrences of length one.
+	 */
+	pathLengths: number[];
+
+	/** The highest number previous attempts on a sequenced edit. */
+	maxAttemptCount: number;
+}
+
+/**
+ * Aggregates and logs telemetry about the success of concurrent edits.
+ */
+export class SharedTreeMergeHealthTelemetryHeartbeat {
+	private heartbeatTimerId = 0;
+	private readonly treeData = new Map<SharedTree, { tally: MergeHealthStats; logger?: ITelemetryLogger }>();
+
+	/**
+	 * Adds a tree to the set of tree to log merge health telemetry for.
+	 * Noop if such a tree was already in the set.
+	 * @param tree - The tree to log merge health telemetry for.
+	 */
+	public attachTree(tree: SharedTree) {
+		if (this.treeData.has(tree) === false) {
+			this.resetTreeData(tree);
+			tree.on(SharedTreeEvent.SequencedEditApplied, this.sequencedEditHandler);
+		}
+	}
+
+	/**
+	 * Removes a tree from the set of tree to log merge health telemetry for.
+	 * Noop if such a tree was never in the set.
+	 * @param tree - The tree to stop logging merge health telemetry for.
+	 */
+	public detachTree(tree: SharedTree) {
+		if (this.treeData.has(tree)) {
+			tree.off(SharedTreeEvent.SequencedEditApplied, this.sequencedEditHandler);
+			this.treeData.delete(tree);
+		}
+	}
+
+	/**
+	 * Exposes the aggregated statistics about merge health for the given tree.
+	 * @param tree - The tree to get stats for.
+	 * @returns Aggregated statistics about merge health for the given tree.
+	 */
+	public getStats(tree: SharedTree): MergeHealthStats {
+		return assertNotUndefined(this.treeData.get(tree), 'No such tree was attached to the logger').tally;
+	}
+
+	/**
+	 * Removes all trees from the set of tree to log merge health telemetry for.
+	 */
+	public detachAllTrees() {
+		for (const tree of this.treeData.keys()) {
+			this.detachTree(tree);
+		}
+	}
+
+	/**
+	 * Resets the aggregated merge health data for the given tree.
+	 * @param tree - The tree to reset the merge health data for.
+	 */
+	public resetTreeData(tree: SharedTree): void {
+		this.treeData.set(tree, {
+			tally: {
+				maxAttemptCount: 0,
+				pathLengths: [],
+				editCount: 0,
+				failedEditCount: 0,
+				badPlaceCount: 0,
+				badRangeCount: 0,
+
+				deletedAncestorBadPlaceCount: 0,
+				deletedAncestorBadRangeCount: 0,
+
+				deletedSiblingBadPlaceCount: 0,
+				deletedSiblingBadRangeCount: 0,
+				updatedRangeInvertedCount: 0,
+				updatedRangeHasPlacesInDifferentTraitsCount: 0,
+				updatedRangeBadPlaceCount: 0,
+				updatedRangeNeverValidPlaceCount: 0,
+
+				constraintViolationCount: 0,
+				rangeConstraintViolationCount: 0,
+				lengthConstraintViolationCount: 0,
+				parentConstraintViolationCount: 0,
+				labelConstraintViolationCount: 0,
+
+				idAlreadyInUseCount: 0,
+				unknownIdCount: 0,
+				malformedEditCount: 0,
+			},
+		});
+	}
+
+	/**
+	 * Enables the regular telemetry logging of merge health data.
+	 * The first message will be sent after `interval` milliseconds. See {@link SharedTreeMergeHealthTelemetryHeartbeat.flushHeartbeat} for
+	 * immediate logging.
+	 * @param interval - The amount of time in milliseconds between log messages.
+	 */
+	public startHeartbeat(interval: number = 60000): void {
+		if (this.heartbeatTimerId !== 0) {
+			this.stopHeartbeat();
+		}
+		this.heartbeatTimerId = window.setInterval(this.logHeartbeat, interval);
+	}
+
+	/**
+	 * Disables the regular telemetry logging of merge health data.
+	 */
+	public stopHeartbeat(): void {
+		window.clearInterval(this.heartbeatTimerId);
+		this.heartbeatTimerId = 0;
+	}
+
+	/**
+	 * Sends all collected merge health data and resets the aggregated state.
+	 */
+	public flushHeartbeat(): void {
+		this.logHeartbeat();
+		this.clearData();
+	}
+
+	/**
+	 * Resets all aggregated state.
+	 */
+	public clearData(): void {
+		for (const tree of this.treeData.keys()) {
+			this.resetTreeData(tree);
+		}
+	}
+
+	/**
+	 * Receives SequencedEditApplied events from trees.
+	 */
+	private readonly sequencedEditHandler = (params: SequencedEditAppliedEventArguments) => {
+		const { edit, tree, wasLocal, logger, outcome, reconciliationPath } = params;
+		if (wasLocal) {
+			const tallyAndLogger = this.treeData.get(tree) ?? fail('Should only receive events for registered trees');
+			tallyAndLogger.logger = logger;
+			const tally = tallyAndLogger.tally;
+			tally.editCount += 1;
+			tally.pathLengths[reconciliationPath.length] = (tally.pathLengths[reconciliationPath.length] ?? 0) + 1;
+			if (edit.pastAttemptCount !== undefined && edit.pastAttemptCount > tally.maxAttemptCount) {
+				tally.maxAttemptCount = edit.pastAttemptCount;
+			}
+			if (outcome.status !== EditStatus.Applied) {
+				tally.failedEditCount += 1;
+				switch (outcome.failure.kind) {
+					case TransactionInternal.FailureKind.BadPlace: {
+						tally.badPlaceCount += 1;
+						if (outcome.failure.placeFailure === PlaceValidationResult.MissingSibling) {
+							tally.deletedSiblingBadPlaceCount += 1;
+						} else if (outcome.failure.placeFailure === PlaceValidationResult.MissingParent) {
+							tally.deletedAncestorBadPlaceCount += 1;
+						}
+						break;
+					}
+					case TransactionInternal.FailureKind.BadRange: {
+						tally.badRangeCount += 1;
+						switch (outcome.failure.rangeFailure) {
+							case RangeValidationResultKind.Inverted:
+								tally.updatedRangeInvertedCount += 1;
+								break;
+							case RangeValidationResultKind.PlacesInDifferentTraits:
+								tally.updatedRangeHasPlacesInDifferentTraitsCount += 1;
+								break;
+							case RangeValidationResultKind.BadPlace:
+								tally.updatedRangeBadPlaceCount += 1;
+								break;
+							default:
+								break;
+						}
+						break;
+					}
+					case TransactionInternal.FailureKind.ConstraintViolation: {
+						tally.constraintViolationCount += 1;
+						switch (outcome.failure.violation.kind) {
+							case TransactionInternal.ConstraintViolationKind.BadRange: {
+								tally.rangeConstraintViolationCount += 1;
+							}
+							case TransactionInternal.ConstraintViolationKind.BadLength: {
+								tally.lengthConstraintViolationCount += 1;
+								break;
+							}
+							case TransactionInternal.ConstraintViolationKind.BadParent: {
+								tally.parentConstraintViolationCount += 1;
+								break;
+							}
+							case TransactionInternal.ConstraintViolationKind.BadLabel: {
+								tally.labelConstraintViolationCount += 1;
+								break;
+							}
+							default: {
+								// If this doesn't type-check, the above switch statement needs to be extended to handle a new case.
+								const _: never = outcome.failure.violation;
+							}
+						}
+						break;
+					}
+					case TransactionInternal.FailureKind.IdAlreadyInUse: {
+						tally.idAlreadyInUseCount += 1;
+						break;
+					}
+					case TransactionInternal.FailureKind.UnknownId: {
+						tally.unknownIdCount += 1;
+						break;
+					}
+					case TransactionInternal.FailureKind.DetachedSequenceIdAlreadyInUse:
+					case TransactionInternal.FailureKind.DetachedSequenceNotFound:
+					case TransactionInternal.FailureKind.DuplicateIdInBuild:
+					case TransactionInternal.FailureKind.UnusedDetachedSequence: {
+						tally.malformedEditCount += 1;
+						break;
+					}
+					default: {
+						// If this doesn't type-check, the above switch statement needs to be extended to handle a new case.
+						const _: never = outcome.failure;
+					}
+				}
+			}
+		}
+	};
+
+	/**
+	 * Logs the accumulated merge health data to each tree's designated logger.
+	 */
+	private readonly logHeartbeat = () => {
+		for (const [tree, { tally, logger }] of this.treeData) {
+			if (logger && tally.editCount > 0) {
+				// Note: all this data is for sequenced edits that were originally produced by the local client.
+				logger.send({
+					category: 'Heartbeat',
+					eventName: 'EditMergeHealth',
+					...tally,
+					// The counts of occurrences for a given path length.
+					// '1:2' means two occurrences of length one.
+					// Overwrites `tally.pathLengths` which is incompatible with ITelemetryBaseEvent.
+					pathLengths: pathLengthsCounts(tally.pathLengths),
+				});
+				this.resetTreeData(tree);
+			}
+		}
+	};
+}
+
+function pathLengthsCounts(lengths: readonly number[]): string {
+	return Object.entries(lengths)
+		.map(([length, count]) => `${length}:${count}`)
+		.join(',');
+}

package/src/NodeIdUtilities.ts

@@ -0,0 +1,141 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from './Common';
+import { IdCompressor, isFinalId } from './id-compressor';
+import { FinalNodeId, NodeId, OpSpaceNodeId, SessionId, StableNodeId } from './Identifiers';
+import { NodeData } from './persisted-types';
+
+/**
+ * An object which can generate node IDs and convert node IDs between compressed and stable variants
+ * @public
+ */
+export interface NodeIdContext extends NodeIdGenerator, NodeIdConverter {}
+
+/**
+ * An object which can generate node IDs
+ * @public
+ */
+export interface NodeIdGenerator {
+	/**
+	 * Generate an identifier that may be used for a new node that will be inserted into this tree
+	 * @param override - an optional string ID to associate with the new id for future lookup. The same override always returns the same ID.
+	 */
+	generateNodeId(override?: string): NodeId;
+}
+
+/**
+ * An object which can convert node IDs between compressed and stable variants
+ * @public
+ */
+export interface NodeIdConverter {
+	/**
+	 * Given a NodeId, return the corresponding UUID. The result is safe to persist and re-use across `SharedTree` instances, unlike NodeId
+	 */
+	convertToStableNodeId(id: NodeId): StableNodeId;
+
+	/**
+	 * Given a NodeId, attempt to return the corresponding UUID.
+	 * The returned UUID is undefined if no such ID was ever created. If a UUID is returned, it is not guaranteed to be in the current
+	 * revision (but it is guaranteed to exist in at least one prior revision).
+	 */
+	tryConvertToStableNodeId(id: NodeId): StableNodeId | undefined;
+
+	/**
+	 * Given an UUID, return the corresponding NodeId.
+	 * The returned NodeId is not guaranteed to be in the current revision (but it is guaranteed to exist in at least one prior revision).
+	 */
+	convertToNodeId(id: StableNodeId): NodeId;
+
+	/**
+	 * Given an UUID, attempt to return the corresponding NodeId.
+	 * The returned NodeId is undefined if no such ID was ever created. If a NodeId is returned, it is not guaranteed to be in the current
+	 * revision (but it is guaranteed to exist in at least one prior revision).
+	 */
+	tryConvertToNodeId(id: StableNodeId): NodeId | undefined;
+}
+
+/**
+ * An object which can normalize node IDs. See docs on {@link IdCompressor} for semantics of normalization.
+ */
+export interface NodeIdNormalizer<TId extends OpSpaceNodeId> {
+	localSessionId: SessionId;
+	/**
+	 * Normalizes the given ID to op space
+	 */
+	normalizeToOpSpace(id: NodeId): TId;
+	/**
+	 * Normalizes the given ID to session space
+	 */
+	normalizeToSessionSpace(id: TId, sessionId: SessionId): NodeId;
+}
+
+/**
+ * An object which can normalize node IDs. It is contextualized to a known session context, and therefore
+ * can normalize IDs into session space without requiring any additional information.
+ */
+export interface ContextualizedNodeIdNormalizer<TId extends OpSpaceNodeId>
+	extends Omit<NodeIdNormalizer<TId>, 'localSessionId' | 'normalizeToSessionSpace'> {
+	/**
+	 * Normalizes the given ID to session space
+	 */
+	normalizeToSessionSpace(id: TId): NodeId;
+}
+
+/**
+ * Create a {@link ContextualizedNodeIdNormalizer} that uses either the given session ID to normalize IDs
+ * to session space. If no ID is given, it will use the local session ID belonging to the normalizer.
+ */
+export function scopeIdNormalizer<TId extends OpSpaceNodeId>(
+	idNormalizer: NodeIdNormalizer<TId>,
+	sessionId?: SessionId
+): ContextualizedNodeIdNormalizer<TId> {
+	return {
+		normalizeToOpSpace: (id) => idNormalizer.normalizeToOpSpace(id),
+		normalizeToSessionSpace: (id) =>
+			idNormalizer.normalizeToSessionSpace(id, sessionId ?? idNormalizer.localSessionId),
+	};
+}
+
+/**
+ * Create a {@link ContextualizedNodeIdNormalizer} that uses the local session ID belonging to the normalizer
+ * to normalize IDs to session space. These IDs are expected to be sequenced, and will fail to normalize if
+ * they are not.
+ */
+export function sequencedIdNormalizer<TId extends OpSpaceNodeId>(
+	idNormalizer: NodeIdNormalizer<TId>
+): ContextualizedNodeIdNormalizer<FinalNodeId & TId> {
+	return {
+		normalizeToOpSpace: (id) => {
+			const normalized = idNormalizer.normalizeToOpSpace(id);
+			assert(isFinalId(normalized));
+			return normalized;
+		},
+		normalizeToSessionSpace: (id) => {
+			const normalized = idNormalizer.normalizeToSessionSpace(id, idNormalizer.localSessionId);
+			assert(isFinalId(normalized));
+			return normalized;
+		},
+	};
+}
+
+export function getNodeIdContext(compressor: IdCompressor): NodeIdContext & NodeIdNormalizer<OpSpaceNodeId> {
+	return {
+		generateNodeId: (override?: string) => compressor.generateCompressedId(override) as NodeId,
+		convertToNodeId: (id: StableNodeId) => compressor.recompress(id) as NodeId,
+		tryConvertToNodeId: (id: StableNodeId) => compressor.tryRecompress(id) as NodeId | undefined,
+		convertToStableNodeId: (id: NodeId) => compressor.decompress(id) as StableNodeId,
+		tryConvertToStableNodeId: (id: NodeId) => compressor.tryDecompress(id) as StableNodeId,
+		normalizeToOpSpace: (id: NodeId) => compressor.normalizeToOpSpace(id) as OpSpaceNodeId,
+		normalizeToSessionSpace: (id: OpSpaceNodeId, sessionId: SessionId) =>
+			compressor.normalizeToSessionSpace(id, sessionId) as NodeId,
+		localSessionId: compressor.localSessionId,
+	};
+}
+
+/** Accepts either a node or a node's identifier, and returns the identifier */
+export function getNodeId<TId extends number | string>(node: TId | NodeData<TId>): TId {
+	return (node as NodeData<TId>).identifier ?? (node as TId);
+}