[Internal] Diagnostics: Adds spec for CosmosDiagnostics compaction summary mode

[NaluTripician]

Summary

Adds a spec sheet for the diagnostics compaction feature that introduces a DiagnosticsVerbosity option (Detailed vs Summary) to reduce unbounded diagnostics output size during high-retry scenarios (429 throttling, transient failures, cross-region failovers).

Spec location: specs/diagnostics-compaction.md

Key Design Decisions

• Summary mode groups requests by region, keeps first/last in full detail, deduplicates middle requests with aggregate stats (count, RU, min/max/P50/avg latency)
• Default is Detailed — no behavioral change for existing users
• Configuration: CosmosClientOptions.DiagnosticsVerbosity + per-request RequestOptions.DiagnosticsVerbosity override + env vars
• Max summary size: 8KB default (4KB min), with truncated fallback
• Compaction is serialization-only — in-memory ITrace tree is unchanged

Reference

Modeled after the Rust SDK's approach: Azure/azure-sdk-for-rust#3592

Work Items

#	Work Item	Description
1	Enum & Options Plumbing	DiagnosticsVerbosity enum, properties on CosmosClientOptions/RequestOptions, env var support
2	Summary Computation Engine	Trace tree walk, region grouping, first/last/aggregated groups
3	Serialization Integration	Branch ToString() on verbosity, size enforcement, truncated fallback
4	Contract Updates	Update ContractEnforcementTests baselines
5	Unit Tests	21 tests covering summary engine, verbosity flow, edge cases
6	Integration Tests	Emulator-based tests for real operations with summary mode
7	Baseline Tests	Golden-file JSONs for summary mode serialization stability

Please review the spec and leave feedback before implementation begins.

#5325

[github-actions]

All good!

[NaluTripician]

Addressed in latest push — good call that since compaction is serialization-only, it doesn't belong on RequestOptions. Changes:

• Removed DiagnosticsVerbosity? from RequestOptions entirely
• Added ToString(DiagnosticsVerbosity) and ToJsonString(DiagnosticsVerbosity) overloads on CosmosDiagnostics so callers control verbosity at serialization time
• Kept CosmosClientOptions.DiagnosticsVerbosity as a client-wide default that flows to CosmosDiagnostics.Verbosity (used by parameterless ToString()) — useful for centralized logging pipelines
• Simplified precedence: ToString(param) > Verbosity property (from client options) > env var > default

[FabianMeiswinkel]

Why even have this property when there is a ToString overload accepting it? IMO this is not needed and introduces weird race conditions - just drop it - ToString() defaults to Detailed (backwards compatibility) and anyone else can use the new overloads.

[FabianMeiswinkel]

LGTM except for the DiagnosticsVerbosity on CosmsoDiagnostics

[kirankumarkolli]

What's the impact of it on the fidelity of the troubleshooting context?

[kirankumarkolli]

Cross partition queries are other bigger source of issues.

[kirankumarkolli]

What's the guidance for customers on when to use what?

[kirankumarkolli]

JSON is verbose, thouhgts on encoding which might help/

[NaluTripician]

Thoughts from offline discussion:

• Consider a hybrid format with JSON text readable summary + encoded information that contains more details for debugging. Have an easy way to decode the information for IcMs + general debugging. Decoding would have to also be available for customers. Possibly add a tool in the repo to do this. Could be standardized across SDKs.

[NaluTripician]

Also important, how can we preserve important information such as which replicas are contacted/failing?

[NaluTripician]

Review Summary

Overall: The specs are impressively thorough — particularly retry-and-failover (324 lines) and diagnostics-and-observability (399 lines). The OpenSpec infrastructure is well-structured. However, there are several accuracy and consistency issues to address before merge.

Findings: 6 Recommendations, 3 Suggestions, 3 Observations (0 Blocking)

Key concerns:

1. Diagnostics spec includes proposed DiagnosticsVerbosity API as if it already exists (files referenced don't exist yet)
2. MaxRetryWaitTime default inconsistent across specs (30s vs 60s)
3. Contradictory requirements around ToString() and verbosity precedence
4. Prior review feedback (hybrid encoding, cross-partition queries) not captured in alternatives
5. PR description is stale — still references RequestOptions.DiagnosticsVerbosity which was deferred

Existing comments cross-reference: Found 9 prior comments from @FabianMeiswinkel and @kirankumarkolli on the old specs/diagnostics-compaction.md. Key feedback was addressed (RequestOptions.DiagnosticsVerbosity deferred, CosmosDiagnostics.Verbosity property removed), but some discussion points weren't captured in the new artifacts.

Additional observations:

• Missing trailing newlines on all 22 new .md files
• No enforcement mechanism for spec maintenance (no CI check, no PR template checkbox)
• External dependency on openspec-dev/openspec tool not documented as a risk
• Distributed transactions spec is very thin (56 lines, mostly open questions) — consider keeping in changes/ until it matures
• Commit history includes unrelated merge-through commits — consider squashing on merge

---

_{⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.}

[NaluTripician]

🟡 Recommendation · Maintainability: Spec Accuracy

Spec references files that don't exist yet

The References section lists DiagnosticsVerbosity.cs and DiagnosticsSummaryWriter.cs as source files, but these are files to be created (per design.md). I verified via the GitHub API that neither file exists in the repository today.

Since this spec catalog is positioned as 'authoritative context for implementation' and 'living documentation,' AI agents reading this spec will attempt to reference or call APIs from these non-existent files. More broadly, the entire DiagnosticsVerbosity section (~200 lines of the 399-line spec) describes proposed behavior mixed in with existing behavior, with no visual distinction.

Suggestion: Either (a) add a clear > :construction: PROPOSED — Not yet implemented callout to all DiagnosticsVerbosity sections, or (b) defer adding them to the main spec until the implementation PR merges — the openspec/changes/diagnostics-compaction/ artifacts already capture the full design.

---

_{⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.}

[NaluTripician]

🟡 Recommendation · Correctness: Inconsistent Default

MaxRetryWaitTime default disagrees with client-and-configuration spec

This table says 'Max cumulative wait time' defaults to 60 seconds. However, openspec/specs/client-and-configuration/spec.md says MaxRetryWaitTimeOnRateLimitedRequests defaults to 30 seconds.

I verified both values in the source:

• RetryOptions.DefaultMaxRetryWaitTimeInSeconds = 30 (the public-facing default)
• ResourceThrottleRetryPolicy.DefaultMaxWaitTimeInSeconds = 60 (internal policy fallback)

The effective customer-facing default is 30 seconds since CosmosClientOptions always passes RetryOptions values to the policy constructor. The 60s value here cites the internal policy fallback, not what customers experience.

Suggestion: Update this table to say 30 seconds (matching the effective default), or add a note: '60s is the internal policy fallback; effective default is 30s per CosmosClientOptions.'

---

_{⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.}

[NaluTripician]

🟡 Recommendation · Correctness: Contradictory Requirements

Verbosity precedence contradicts 'Parameterless ToString always returns Detailed'

This section defines a 3-tier precedence: (1) explicit ToString(DiagnosticsVerbosity) parameter → (2) CosmosClientOptions.DiagnosticsVerbosity → (3) default Detailed.

But line 169 says: 'Parameterless ToString() always returns Detailed, regardless of CosmosClientOptions.DiagnosticsVerbosity setting.'

These two requirements contradict each other. If parameterless ToString() always returns Detailed regardless of the client option, then CosmosClientOptions.DiagnosticsVerbosity has no effect — there's no call path that consults it (since ToString(verbosity) already has an explicit parameter, and ToString() ignores it).

Suggestion: Clarify the intent: either (a) parameterless ToString() respects CosmosClientOptions.DiagnosticsVerbosity as its default (remove the 'regardless' clause on line 169), or (b) CosmosClientOptions.DiagnosticsVerbosity only provides a convenience default for callers who construct the verbosity parameter from config (document this explicitly). As written, the option appears useless.

---

_{⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.}

[NaluTripician]

🟡 Recommendation · Completeness: Missing Alternative

Hybrid encoding alternative from review discussion not captured

@kirankumarkolli raised 'JSON is verbose, thoughts on encoding which might help?' and @NaluTripician replied with thoughts from offline discussion: 'Consider a hybrid format with JSON text readable summary + encoded information that contains more details for debugging.'

This is a substantive alternative approach that emerged from review, but it's not listed in the Alternatives Considered section. Future readers won't know this option was discussed and evaluated.

Suggestion: Add 'Alternative 4: Hybrid format (readable summary + encoded details)' with pros/cons and decision rationale, even if the decision is to defer. This preserves the design context from the review discussion.

---

_{⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.}

[NaluTripician]

🟡 Recommendation · Completeness: Scope Gap

Cross-partition query diagnostics growth not addressed

@kirankumarkolli noted 'Cross partition queries are other bigger source of issues.' The proposal focuses on retry-heavy scenarios (429 throttling, failover), but cross-partition queries can produce large diagnostics due to fan-out across many physical partitions — regardless of retries.

A query fanning out to 50 partitions produces 50 separate ClientSideRequestStatisticsTraceDatum entries even without any retries. Summary mode's region-grouping helps somewhat, but the compaction algorithm (first/last + aggregated middle) is designed for the retry pattern, not the fan-out pattern.

Suggestion: Add a 'Scope Limitations' note or expand 'Non-Goals' to acknowledge that cross-partition query fan-out diagnostics are not addressed in this phase, and note whether a future phase could address it.

---

_{⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.}

[NaluTripician]

🟢 Suggestion · Completeness: Replica Information

Consider preserving replica/endpoint information in summary mode

@NaluTripician noted in PR comments: 'Also important, how can we preserve important information such as which replicas are contacted/failing?' This concern isn't addressed in the current spec.

Summary mode compacts middle requests into aggregated stats, but replica-level detail (which specific replicas were contacted, which failed) is potentially lost. This information is critical for IcM debugging — knowing that replica X in region Y is the one failing is often the key diagnostic signal.

Suggestion: Add a requirement or open question about preserving replica/endpoint information in summary mode output. At minimum, the First and Last entries preserve this, but consider whether aggregated groups should include a distinct endpoint count or list.

---

_{⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.}