Visitar URL original
Add diagnostic string support by andrewlazenka · Pull Request #26548 · Azure/azure-sdk-for-go · GitHub
Skip to content

Add diagnostic string support - #26548

Merged
Fabian Meiswinkel (FabianMeiswinkel) merged 14 commits into
Azure:mainfrom
andrewlazenka:diagnostic-string
May 8, 2026
Merged

Fabian Meiswinkel (FabianMeiswinkel) merged 14 commits into
Azure:mainfrom
andrewlazenka:diagnostic-string

Conversation

@andrewlazenka

@andrewlazenka Andrew Lazenka (andrewlazenka) commented Apr 9, 2026 •

Copy link
Copy Markdown
Contributor

This PR adds diagnostic string support to the azcosmos package. Responses now carry a Diagnostics value, and callers can also recover diagnostics from failures via DiagnosticsFromError(err). The diagnostics render as a structured JSON payload for troubleshooting latency and failures, including request timing, retry/gateway history, regions contacted, HTTP stats, RU charges, and query metrics.

Architecture

The implementation now uses a mutable collection phase plus an immutable finalized diagnostics phase.

trace.go — Trace collection and finalization

  • trace is the mutable tree used while an operation is in flight.
  • finalizedTrace is an immutable snapshot created when diagnostics are handed off to a response or error.
  • traceSummary tracks failed backend attempts across the tree.
  • startSpan() mirrors the azruntime.StartSpan hierarchy into the diagnostics tree.

trace_data.go — Trace datum types and request-scoped state

  • requestDiagnosticsState stores the request trace, client-side stats, resource type, and request session token in context.Context.
  • clientSideRequestStatisticsTraceDatum records per-attempt HTTP response/error stats, regions contacted, address-resolution stats, and force-refresh data.
  • pointOperationStatisticsTraceDatum captures point-operation metadata such as activity ID, status/substatus, RU charge, session tokens, and backend latency.
  • Helpers attach diagnostics to outgoing requests and record point-operation/query-metric data from responses.

trace_json_writer.go — JSON serialization

  • Serializes finalized diagnostics into the JSON shape exposed to callers.
  • Produces the Summary, root trace, nested data, and children sections from immutable snapshots.
  • Summary collection walks finalized state instead of live mutable traces.

diagnostics.go — Public API surface

  • Diagnostics holds finalized immutable state plus the failed-request count.
  • String(), ClientElapsedTime(), StartTimeUTC(), and FailedRequestCount() read from that finalized snapshot.
  • DiagnosticsFromError(err) works with both wrapped request errors and azcore.ResponseError.

Integration points (modified files)

File Changes
cosmos_client.go Attaches request diagnostics during request creation, records point-operation stats, and finalizes request traces before surfacing responses or errors.
cosmos_container.go / cosmos_database.go Use startSpan() so operation trees flow into diagnostics; ReadManyItems now finalizes its operation trace before returning diagnostics.
cosmos_client_retry_policy.go Records per-attempt HTTP response/error statistics into client-side diagnostics.
cosmos_response.go and response helpers Add/populate Diagnostics on response types from the request context.
cosmos_query_response.go Records query metrics before diagnostics are finalized and includes Diagnostics on ReadManyItemsResponse.
cosmos_offers.go / trace_data.go Use lightweight request-charge parsing where only charge data is needed, avoiding accidental mid-request diagnostics capture.

Tests

  • diagnostics_test.go covers:
    • summary diagnostics for a retried gateway call (503 → 200)
    • diagnostics extracted from azcore.ResponseError
    • query response diagnostics including query metrics
    • ReadManyItems diagnostics remaining stable after return
    • representative exact rendered JSON samples for gateway-summary, response-error, and query-metrics scenarios

Checklist

  • The purpose of this PR is explained in this or a referenced issue.
  • The PR does not update generated files.
  • Tests are included and/or updated for code changes.
  • Updates to module CHANGELOG.md are included.
  • MIT license headers are included in each file.

@github-actions github-actions Bot added Community Contribution Community members are working on the issue Cosmos customer-reported Issues that are reported by GitHub users external to the Azure organization. labels Apr 9, 2026
@github-actions

github-actions Bot commented Apr 9, 2026

Copy link
Copy Markdown

Thank you for your contribution Andrew Lazenka (@andrewlazenka)! We will review the pull request and get back to you soon.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Largely looks good, but I think there's some unnecessary complication around how handling building diagnostics while serializing them that could be cleaned up a bit and made clearer.

I'd also like to see a few tests showing the final rendered JSON of some sample diagnostics strings. It doesn't need to be complete coverage of all variations of diagnostics strings, but some core cases.

Comment thread sdk/data/azcosmos/trace.go Resolved
@analogrelay

Copy link
Copy Markdown
Member

Andrew Lazenka (@andrewlazenka) Go ahead and undraft this if you're ready! I've done a high-level pass and it looks pretty solid, but I'd like some more of the team (particularly those with a little more experience with the diagnostics strings in other SDKs) to take a look. I'll pass the PR around a bit and we'll put some resources into reviewing it.

Thanks for the contribution!

@andrewlazenka Andrew Lazenka (andrewlazenka) changed the title Diagnostic string Add diagnostic string support Apr 14, 2026
@andrewlazenka
Andrew Lazenka (andrewlazenka) marked this pull request as ready for review April 14, 2026 20:05
@andrewlazenka
Andrew Lazenka (andrewlazenka) requested a review from a team as a code owner April 14, 2026 20:05
Copilot AI review requested due to automatic review settings April 14, 2026 20:05

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR introduces end-to-end diagnostics capture and rendering for azcosmos operations, enabling callers to get a structured JSON diagnostics string from successful responses and also recover diagnostics from errors.

Changes:

  • Adds a mutable trace collection model with an immutable “finalized” snapshot and JSON serialization for diagnostics payloads.
  • Populates Diagnostics on response types and wires diagnostics extraction via DiagnosticsFromError(err).
  • Records per-attempt HTTP stats (including retries), point-operation metadata, and query metrics into diagnostics.
Show a summary per file
File Description
sdk/data/azcosmos/trace_json_writer.go Adds JSON serialization for finalized traces plus summary aggregation.
sdk/data/azcosmos/trace_data.go Adds request-scoped diagnostics state and trace datum types for HTTP stats and point/query metadata.
sdk/data/azcosmos/trace.go Implements mutable trace tree, finalization to immutable snapshots, and span integration.
sdk/data/azcosmos/diagnostics.go Introduces public Diagnostics type and DiagnosticsFromError extraction API.
sdk/data/azcosmos/diagnostics_test.go Adds tests covering diagnostics rendering, summary behavior, and error extraction.
sdk/data/azcosmos/throughput_response.go Wraps unmarshal errors with diagnostics-aware error wrapping.
sdk/data/azcosmos/cosmos_transactional_batch_response.go Wraps unmarshal errors with diagnostics-aware error wrapping.
sdk/data/azcosmos/cosmos_response.go Adds Diagnostics to Response and centralizes request-charge parsing.
sdk/data/azcosmos/cosmos_query_response.go Records query metrics into trace before diagnostics are finalized; wraps errors to preserve diagnostics.
sdk/data/azcosmos/cosmos_partition_key_range_response.go Wraps payload/unmarshal errors with diagnostics-aware error wrapping.
sdk/data/azcosmos/cosmos_offers.go Uses lightweight request-charge parsing without instantiating full response/diagnostics.
sdk/data/azcosmos/cosmos_item_response.go Wraps payload errors with diagnostics-aware error wrapping.
sdk/data/azcosmos/cosmos_database_response.go Wraps unmarshal errors with diagnostics-aware error wrapping.
sdk/data/azcosmos/cosmos_database.go Switches span creation to diagnostics-aware startSpan() for trace alignment.
sdk/data/azcosmos/cosmos_container_response.go Wraps unmarshal errors with diagnostics-aware error wrapping.
sdk/data/azcosmos/cosmos_container.go Switches to diagnostics-aware spans; finalizes ReadManyItems operation trace and returns diagnostics.
sdk/data/azcosmos/cosmos_client_retry_policy.go Records per-attempt HTTP errors/responses into client-side request statistics.
sdk/data/azcosmos/cosmos_client.go Attaches request diagnostics to outgoing requests; records point-operation stats; wraps non-response errors with diagnostics.
sdk/data/azcosmos/cosmos_change_feed_response.go Wraps payload/unmarshal errors with diagnostics-aware error wrapping.

Copilot's findings

  • Files reviewed: 19/19 changed files
  • Comments generated: 6

Comment thread sdk/data/azcosmos/trace_data.go Resolved
Comment thread sdk/data/azcosmos/trace_json_writer.go Resolved
Comment thread sdk/data/azcosmos/trace_json_writer.go Resolved
Comment thread sdk/data/azcosmos/trace_json_writer.go Resolved
Comment thread sdk/data/azcosmos/cosmos_container.go Resolved
Comment thread sdk/data/azcosmos/trace.go Resolved

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few small non-blocking comments and clarifications, but in general I'm good with this. I'd like some folks who are more directly experienced with these diagnostics strings to take a look too though (and I've already asked for their input).

Comment thread sdk/data/azcosmos/trace_json_writer.go Resolved
Comment thread sdk/data/azcosmos/cosmos_container.go Resolved
Comment thread sdk/data/azcosmos/cosmos_client.go Resolved

@simorenoh Simon Moreno (simorenoh) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great to me for the most part, agreed with Ashley's comments - would love if you could add the relevant changelog entry and maybe a readme sample showing how to use them for users. Thanks for this!

@andrewlazenka

Copy link
Copy Markdown
Contributor Author

Simon Moreno (@simorenoh) thanks! added a couple examples to the readme and appended to the changelog.

@andrewlazenka

Copy link
Copy Markdown
Contributor Author

@microsoft-github-policy-service agree company="GitHub"

@FabianMeiswinkel
Fabian Meiswinkel (FabianMeiswinkel) merged commit f1c573a into Azure:main May 8, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Community Contribution Community members are working on the issue Cosmos customer-reported Issues that are reported by GitHub users external to the Azure organization.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants