Azure / Azure/azure-sdk-for-rust

Aggregate buffered Cosmos query metrics

Open
#5,170 0 comments 1 reaction 0 assignees View on GitHub
Client Cosmos
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.