Skip to content

fix(discoveryengine): complete v1 semantic tracing coverage - #377

Open
nik13 wants to merge 1 commit into
devfrom
fix/discoveryengine-operation-coverage
Open

nik13 wants to merge 1 commit into
devfrom
fix/discoveryengine-operation-coverage

Conversation

@nik13

@nik13 nik13 commented Oct 31, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

Keep the Discovery Engine package and complete its v1 semantic operation coverage. Adds sync/async stream_answer_query, converse_conversation, rank and check_grounding without removing the instrumentor entry point or existing search support.

  • Streaming spans cover consumption, preserve chunk identity and caller context, forward cancellation/close, and end once on success, error, cancellation or abandonment. No buffering/prefetching by the instrumentor. Google's final full answer is not concatenated with preceding deltas.
  • Search remains RETRIEVER; answer/conversation operations use CHAIN, ranking uses RERANKER, and grounding uses EVALUATOR. No inferred model/token/cost data. The answer kind change is intentional and covered by the existing collector contracts.
  • capture_content=True opts into a bounded, whitelisted response projection, including answer/citation/reference content and search/ranking/grounding results. Default output capture stays off. Either content-hide flag overrides capture, credential/PII scrubbing precedes truncation, and valid output JSON is bounded to 16 KiB. Errors from newly covered operations suppress server text that may echo private content.
  • Replace the README's verification diary with customer setup, supported operations, streaming lifecycle and privacy controls. No hand-edited version or changelog.

Why?

On unchanged dev d6a9966dd4d5d5fb344f7f5ab11b7483c2c2a6bc, all seven initial regression cases fail because no operation span is exported (six sync/async unary cases and a real loopback gRPC answer stream). A generic transport span is not a replacement for semantic retrieval/answer/ranking/grounding observations.

Coverage reference, inspected rather than copied: Braintrust's exact v1 targets at 3f14f10. Stream behavior follows Google's streamed-answer example, which emits text deltas followed by a complete terminal answer.

How was it tested?

  • 188 passed on Python 3.12, google-cloud-discoveryengine==0.20.5, fi-instrumentation-otel==1.1.0 (core floor).
  • 188 passed with the same SDK and fi-instrumentation-otel==1.2.2 (current registry core). Discovery Engine 0.20.5 is both the supported floor and current PyPI release; these are not claimed as two distinct SDK versions.
  • All runs used outbound-network-denied sandbox-exec, permitting loopback only. The gRPC fixture uses native IPv6 loopback on macOS because its IPv4-mapped IPv6 sockets are denied by that policy; Linux keeps the existing IPv4 fixture.
  • Real sync/async gRPC streams, existing search/REST/error/credential tests, synthetic real-GAPIC unary transports, close/cancel/error/incomplete/failed streams, context restoration, suppression/uninstrumentation, async unary cancellation, response identity, bounded capture and credential/PII controls.
  • Real OTLP encoding plus loopback collector HTTP reception checks default-off capture and both hide flags for all operation families.
  • Runtime lint (ruff --isolated --select E9,F) passes on baseline and changed implementation/new tests; git diff --check passes. Python snippets in README and staged guide parse.
  • No vendor/model API, real credential, cloud deployment or docs-site rendering was used. No gateway/E2E harness exists in this repository; product E2E is not applicable.

Review and rollout

Self-reviewed against internal minimal-code, contracts, failure-mode, typing and scenario-coverage standards. Existing public imports and call shapes remain supported. Search paging remains first-page-only; beta/alpha aliases and administrative RPCs remain deliberately excluded. The new stream proxy delegates vendor methods and adds deterministic close support; callers should exhaust or explicitly close a stream.

Target is dev, per this repair's release workflow (not the template's generic main default). This is a package repair, not a retirement. No merge, tag or publication is performed here.

The existing docs proposal is docs #1019; it covers the older three-operation package. A corrected full guide is staged for its owner after this package reaches PyPI. No competing docs PR is opened and no other author's branch is modified.

Generated with Claude Code

Preserve search support while tracing streamed answers, conversations, ranking and grounding. Keep response content opt-in with bounded privacy controls and lifecycle-safe stream proxies.

Co-Authored-By: Claude Code <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant