Azure / Azure/azure-sdk-for-rust
Aggregate buffered Cosmos query metrics
- Dominant language
- Rust
- Stars
- 884
- Forks
- 365
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 109
Description
### Feature Summary
Define and implement complete query- and index-metrics reporting for Cosmos queries whose client pipeline consumes multiple backend pages before emitting a client-visible page.
### Feature Description
`PageAggregator` currently sums request charges, merges session tokens, and aggregates diagnostics across consumed backend responses, but retains only the latest non-empty `query_metrics` and `index_metrics` header values.
That behavior is generally observable page by page for streaming queries. It becomes incomplete for client-buffered operations: the pipeline may consume every page from every partition before returning its first client-visible page, so callers cannot inspect the discarded intermediate metrics. The final response can consequently contain the total request charge for the operation but metrics from only the last backend response.
This became visible while implementing finite-window cross-partition vector ordering in [PR #5130](https://github.com/Azure/azure-sdk-for-rust/pull/5130), but the design should be resolved for shared query infrastructure rather than through vector-specific behavior.
The design should answer:
- What should query and index metrics represent for an operation that internally consumes multiple pages and partitions?
- Does Cosmos define a canonical multi-partition wire representation or separator for these headers?
- Should the SDK parse and structurally aggregate metrics, preserve a collection of per-response metrics, or expose both forms?
- How should metrics be associated with physical partition ranges and backend activity IDs?
- Which emitted client page should carry operation-level metrics when buffered results are subsequently divided according to `max_item_count`?
- What compatibility constraints apply to the existing raw string fields?
- How should metric retention remain memory-bounded without silently losing information or inventing synthetic service metrics?
- Should the resulting behavior apply to every `PageAggregator` consumer or only pipelines that hide intermediate backend pages?
Expected coverage should include multiple pages from multiple partitions, distinct query/index metric values, summed request charge, merged session tokens, and the chosen output-page semantics.
### Use Case
Customers diagnosing cross-partition buffered queries need metrics that describe all backend work performed on their behalf. This is especially important for native cross-partition vector ordering because the SDK drains all relevant ranges before returning globally ordered results.
### Alternatives
The current latest-non-empty-value behavior preserves compatibility but reports only a subset of the backend work. Concatenating raw strings could preserve more data, but should not be done without confirming the service wire contract. A structured parser or an explicit per-backend-response collection would be more precise but requires API and memory-retention design.
### Additional Context
Reference implementation and motivating scenario: [Azure SDK for Rust PR #5130](https://github.com/Azure/azure-sdk-for-rust/pull/5130). This follow-up allows the pure-vector feature to remain focused while the shared metrics contract is designed independently.
Contributor guide
Research direction
Start by reading the PageAggregator implementation and the motivating Azure SDK for Rust PR #5130. Trace buffered multi-page, multi-partition consumers and determine the metrics contract before changing behavior. Done means documented and tested semantics for query and index metrics, summed request charge, merged session tokens, memory bounds, and the client page carrying operation-level metrics.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend-api-design, databases
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100