docs: document the query wait contract in builders + add example - #4
Open
DoubleTK wants to merge 3 commits into
Open
docs: document the query wait contract in builders + add example#4DoubleTK wants to merge 3 commits into
DoubleTK wants to merge 3 commits into
Conversation
The query builders documented Take/Wait loosely: TakeAll read as "take all within the duration" with no hint it never returns early, and Wait did not note that a zero or unset duration selects the sink's 30s default. That made the long-poll semantics easy to misuse (e.g. TakeAll + client-side retry polling, where a single call always blocks the full window). - Rewrite the TakeFirst/TakeExact/TakeAll/Wait godoc across the span, log, and metric builders to state when each returns. - Add a package doc (doc.go) with the Take/Duration contract and the canonical "wait for a specific signal" pattern (TakeFirst + filter + Wait). - Add a runnable godoc example and a full push->query round-trip under examples/roundtrip (its own module, so the OTLP SDK deps stay out of the library module). Verified against the OddDotNet server (SignalList.QueryAsync). Generated types under gen/ pick up the matching proto comments on the next OddDotProto submodule bump (see OddDotNet/OddDotProto#25). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01J2rAdqyGkWmhGLcfrRYxFy
The example binary was swept in by git add -A; remove it and add a .gitignore so 'go build' output in examples/roundtrip stays untracked. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01J2rAdqyGkWmhGLcfrRYxFy
Bump the proto submodule to OddDotProto main (dbbb59c, #25 merged) and re-run `make generate`. This pulls the newly-documented query API into the generated Go: the proto doc comments now surface as godoc on the gen/ types and fields. Regen is comments + gofmt realignment only — no protobuf-go/grpc API change, no rawDesc/tag/field changes (verified). `go build ./...` passes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0173DeQYX9USX5srXEeJUVqA
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Makes the query wait contract discoverable from the builders instead of only from the sink's source. The builders documented
Take/Waitloosely —TakeAllread as "take all within the duration" (no hint it never returns early), andWaitdidn't mention that a zero/unset duration is the sink's 30s default — which made the long-poll easy to misuse (e.g.TakeAll+ client-side retry polling, where a single call always blocks the full window).Changes
TakeFirst/TakeExact/TakeAll/Waitgodoc across the span, log, and metric builders to state when each returns.builder/doc.go) with theTake/Durationcontract and the canonical "wait for a specific signal" pattern (TakeFirst+ filter +Wait).Example(builder/example_test.go) and a full push→query round-trip underexamples/roundtrip/— its own module so the OpenTelemetry SDK deps stay out of the library module.README.md.The contract (verified against the server)
Confirmed by reading
OddDotNet/SignalList.cs(GetTakeCount+ theQueryAsyncloop):TakeTakeFirst(default)DurationTakeExact(n)DurationTakeAllDurationDurationof zero or unset → 30s default (not "return immediately").Notes
builderorgenbehavior.gen/will pick up the matching schema comments on the next OddDotProto submodule bump — companion PR docs: document the full OddDotProto query API OddDotProto#25.Test plan
go build ./...,go vet ./...,golangci-lint run ./...— cleango test ./builder/...— passes, including the newExampleexamples/roundtripcompiles (go build) and vets🤖 Generated with Claude Code
https://claude.ai/code/session_01J2rAdqyGkWmhGLcfrRYxFy