diff --git a/packages/runtime/container-runtime/src/metadata.ts b/packages/runtime/container-runtime/src/metadata.ts index d43b13c599de..ad150e6b1d6a 100644 --- a/packages/runtime/container-runtime/src/metadata.ts +++ b/packages/runtime/container-runtime/src/metadata.ts @@ -40,6 +40,20 @@ export interface IBatchMetadata { * Maybe set on first message of a batch, to the batchId generated when resubmitting (set/fixed on first resubmit) */ batchId?: BatchId; + /** + * Set on the envelope of a grouped batch op to the number of inner ops it contains. + * Exposed on the wire so consumers can record batch sizes in telemetry without parsing the grouped batch contents. + * + * Observable values: + * - Absent: either this is not a grouped batch envelope (e.g. a singleton batch that bypassed grouping), OR the producing runtime predates this field. Until the rollout is complete, telemetry consumers should treat absence as ambiguous and parse the envelope contents if a precise count is required for a grouped batch. + * - `0`: empty-grouped-batch placeholder produced when a resubmitted batch becomes empty. + * - `N` (N \> 0): grouped batch with N inner ops. For a chunked grouped batch this appears only on the last chunk's envelope (intermediate chunks carry no metadata). + * + * The field is intentionally advisory-only: the runtime does not validate that an inbound value matches the batch's actual inner op count. It is consumed exclusively by off-runtime telemetry. + * + * The field is always (re)stamped at outbound time from the current batch's actual size — `groupBatch` reads `batch.messages.length` directly, `createEmptyGroupedBatch` always writes `0`, and the chunking path only ever sees freshly-grouped envelopes from the same flush. It is never propagated from stashed pending state to the wire: on resubmit, ops re-enter grouping and the count is recomputed from the (possibly squashed, dropped, or added) outbound batch. This means the wire value always reflects the actual outbound size, even when the resubmitted batch differs from the original. + */ + groupedOpCount?: number; } /** diff --git a/packages/runtime/container-runtime/src/opLifecycle/opGroupingManager.ts b/packages/runtime/container-runtime/src/opLifecycle/opGroupingManager.ts index 1a1bb70ee02d..a95d3cbf5e63 100644 --- a/packages/runtime/container-runtime/src/opLifecycle/opGroupingManager.ts +++ b/packages/runtime/container-runtime/src/opLifecycle/opGroupingManager.ts @@ -100,7 +100,7 @@ export class OpGroupingManager { const serializedOp = JSON.stringify(emptyGroupedBatch); const placeholderMessage: LocalEmptyBatchPlaceholder = { - metadata: { batchId: resubmittingBatchId }, + metadata: { batchId: resubmittingBatchId, groupedOpCount: 0 }, localOpMetadata: { emptyBatch: true }, referenceSequenceNumber, runtimeOp: emptyGroupedBatch, @@ -169,7 +169,7 @@ export class OpGroupingManager { ...batch, messages: [ { - metadata: { batchId: groupedBatchId }, + metadata: { batchId: groupedBatchId, groupedOpCount: batch.messages.length }, referenceSequenceNumber: batch.messages[0].referenceSequenceNumber, contents: serializedContent, }, diff --git a/packages/runtime/container-runtime/src/opLifecycle/opSplitter.ts b/packages/runtime/container-runtime/src/opLifecycle/opSplitter.ts index 4f1de77d5a21..ff3b0db41572 100644 --- a/packages/runtime/container-runtime/src/opLifecycle/opSplitter.ts +++ b/packages/runtime/container-runtime/src/opLifecycle/opSplitter.ts @@ -171,12 +171,22 @@ export class OpSplitter { ); } - // The last chunk will be part of the new batch and needs to - // preserve the batch metadata of the original batch + // The last chunk will be part of the new batch and needs to preserve the + // batch metadata of the original batch. groupedOpCount is surfaced here + // (and only here, not on intermediate chunks) because intermediate chunks + // don't carry ops — they carry parts of a payload that only become ops + // once the last chunk is processed and the payload is reassembled. + // Stamping every chunk would let an observer double-count messages. + // batchId is deliberately not forwarded — it's a runtime dedup field + // consumed only after processChunk restores originalMetadata, not by + // wire observers. const lastChunk = chunkToBatchMessage( chunks[chunks.length - 1], batch.referenceSequenceNumber, - { batch: firstMessage.metadata?.batch }, + { + batch: firstMessage.metadata?.batch, + groupedOpCount: firstMessage.metadata?.groupedOpCount, + }, ); this.logger.sendPerformanceEvent({ diff --git a/packages/runtime/container-runtime/src/test/opLifecycle/OpGroupingManager.spec.ts b/packages/runtime/container-runtime/src/test/opLifecycle/OpGroupingManager.spec.ts index 68eae137838e..3dda8c99c908 100644 --- a/packages/runtime/container-runtime/src/test/opLifecycle/OpGroupingManager.spec.ts +++ b/packages/runtime/container-runtime/src/test/opLifecycle/OpGroupingManager.spec.ts @@ -74,7 +74,7 @@ describe("OpGroupingManager", () => { { contents: '{"type":"groupedBatch","contents":[{"contents":0},{"contents":0},{"contents":0},{"contents":0},{"contents":0}]}', - metadata: { batchId: undefined }, + metadata: { batchId: undefined, groupedOpCount: 5 }, referenceSequenceNumber: 0, }, ]); @@ -90,6 +90,7 @@ describe("OpGroupingManager", () => { ).groupBatch(createBatch(5, false, false, batchId)); assert.strictEqual(result.messages.length, 1); assert.strictEqual(result.messages[0].metadata?.batchId, batchId); + assert.strictEqual(result.messages[0].metadata?.groupedOpCount, 5); }); it("empty grouped batching disabled", () => { @@ -111,7 +112,7 @@ describe("OpGroupingManager", () => { const batchId = "batchId"; const expectedOutboundMessage: OutboundBatchMessage = { contents: '{"type":"groupedBatch","contents":[]}', - metadata: { batchId }, + metadata: { batchId, groupedOpCount: 0 }, localOpMetadata: { emptyBatch: true }, referenceSequenceNumber: 0, runtimeOp: undefined, @@ -128,7 +129,7 @@ describe("OpGroupingManager", () => { const expectedPlaceholderMessage: LocalEmptyBatchPlaceholder = { runtimeOp: emptyGroupedBatch, - metadata: { batchId }, + metadata: { batchId, groupedOpCount: 0 }, localOpMetadata: { emptyBatch: true }, referenceSequenceNumber: 0, }; diff --git a/packages/runtime/container-runtime/src/test/opLifecycle/opCompressor.spec.ts b/packages/runtime/container-runtime/src/test/opLifecycle/opCompressor.spec.ts index 4c9d10427b84..84baf1f02bb7 100644 --- a/packages/runtime/container-runtime/src/test/opLifecycle/opCompressor.spec.ts +++ b/packages/runtime/container-runtime/src/test/opLifecycle/opCompressor.spec.ts @@ -41,7 +41,7 @@ describe("OpCompressor", () => { referenceSequenceNumber: messages[0].referenceSequenceNumber, }); const createMessage = (contents: string) => ({ - metadata: { flag: true }, + metadata: { flag: true, groupedOpCount: 7 }, type: ContainerMessageType.FluidDataStoreOp, contents, referenceSequenceNumber: 0, @@ -63,6 +63,7 @@ describe("OpCompressor", () => { assert.strictEqual(compressedBatch.messages.length, batch.messages.length); assert.strictEqual(compressedBatch.messages[0].compression, "lz4"); assert.strictEqual(compressedBatch.messages[0].metadata?.flag, true); + assert.strictEqual(compressedBatch.messages[0].metadata?.groupedOpCount, 7); }).timeout(3000); } }); diff --git a/packages/runtime/container-runtime/src/test/opLifecycle/opSplitter.spec.ts b/packages/runtime/container-runtime/src/test/opLifecycle/opSplitter.spec.ts index 89b9eed5b595..d48e86299e7d 100644 --- a/packages/runtime/container-runtime/src/test/opLifecycle/opSplitter.spec.ts +++ b/packages/runtime/container-runtime/src/test/opLifecycle/opSplitter.spec.ts @@ -398,6 +398,73 @@ describe("OpSplitter", () => { ); }); } + + it("Propagates groupedOpCount onto the last chunk only", () => { + const chunkSize = 20; + const opSplitter = new OpSplitter( + [], + mockSubmitBatchFn, + chunkSize, + maxBatchSizeInBytes, + mockLogger, + ); + const groupedOpCount = 7; + const largeMessage: OutboundBatchMessage = { + ...generateChunkableOp(100), + metadata: { batch: true, groupedOpCount }, + }; + + const result = opSplitter.splitSingletonBatchMessage({ + messages: [largeMessage], + contentSizeInBytes: largeMessage.contents?.length ?? 0, + referenceSequenceNumber: 0, + }); + + // Intermediate chunks (the ones submitted directly) carry no metadata. + for (const submitted of batchesSubmitted) { + assert.strictEqual(submitted.messages.length, 1); + assert.strictEqual(submitted.messages[0].metadata, undefined); + } + + // Last chunk envelope carries both batch flag and groupedOpCount. + assert.strictEqual(result.messages.length, 1); + assert.deepStrictEqual(result.messages[0].metadata, { + batch: true, + groupedOpCount, + }); + + // Reassembly preserves groupedOpCount via originalMetadata on the final chunk's payload. + const reassembler = new OpSplitter( + [], + mockSubmitBatchFn, + chunkSize, + maxBatchSizeInBytes, + mockLogger, + ); + const allChunks = [ + ...batchesSubmitted.map( + (b) => + JSON.parse((b.messages[0] as OutboundBatchMessage).contents!) as { + contents: IChunkedOp; + }, + ), + JSON.parse(result.messages[0].contents!) as { contents: IChunkedOp }, + ].map((parsed) => parsed.contents); + + let final: ISequencedDocumentMessage | undefined; + for (const chunk of allChunks) { + const wrapped = { + contents: { type: ContainerMessageType.ChunkedOp, contents: chunk }, + clientId: "testClient", + } as unknown as ISequencedDocumentMessage; + const processed = reassembler.processChunk(wrapped); + if (processed.isFinalChunk) { + final = processed.message; + } + } + assert(final !== undefined, "Expected reassembly to complete"); + assert.deepStrictEqual(final.metadata, { batch: true, groupedOpCount }); + }); }); const assertSameMessage = ( result: ISequencedDocumentMessage,