Skip to content

Say that reports still queued at close()'s timeout are sent afterwards, not dropped - #41

Merged
dmccoystephenson merged 1 commit into
mainfrom
trace/close-timeout-docs
Nov 14, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
trace/close-timeout-docs

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

Stage A documentation accuracy sweep. One drift was found and fixed:

  • close() timeout behaviour. The close() docstring opens with "Stop the sending thread" and the README's "close() drains" row says reports get the timeout "before the thread stops". Both read as if anything still unsent is dropped when the timeout runs out. In trace_client/trace_client.py, close() only does thread.join(timeout). The daemon sender keeps draining the queue after close() returns and stops when it reaches the sentinel. Anything it has not sent by process exit is lost. (The existing test_close_on_a_full_queue_drops_the_oldest_report_and_still_stops_the_sender already depends on this: 256 reports are delivered after a 0.5 s close().) The docstring and README now say this, and the README now mentions close(timeout=...).
  • Tag-cap wording. The README now says the 32-tag cap that keeps install off an event counts version too. This matches _with_install, which checks len(tags) >= MAX_TAGS after version has been merged in.
  • New characterization test. test_reports_still_queued_at_the_timeout_are_sent_after_close_returns covers the newly documented behaviour. No production logic changed.

The rest of the sweep found no drift in: the constructor signature, the promises table, opt-out values, precedence and disabled_reason strings, the wire-format section, the Building section against build.yml (3.8/3.10/3.12), the module headers, pyproject.toml, and __all__.

Deferred

Java parity

No Java-visible behaviour changed: this is documentation plus a test. The Java README could not be read during this session, so whether its close() docs have the same wording is unverified.

Test plan

  • python3 -m unittest: 78 tests ran, OK (local Python 3.8.10)
  • CI test (3.8), test (3.10), test (3.12) green

No tracking issue — gap found during the documentation sweep.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code


drafted by Claude on behalf of Daniel Stephenson

…s, not dropped

close(timeout) returns once the timeout runs out, but the daemon sender keeps
draining what was queued and only stops when it reaches the sentinel. The
docstring and README read as if the thread stopped at the timeout. Say what
actually happens, mention close(timeout=...) in the README, pin the behaviour
with a test, and say the 32-tag cap counts version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric (anchored on CI run 43548303032 and the diff):

  • Scope: PASS. Three files: the close() docstring, two README lines, and one new test. Each one serves the documented close() timeout behaviour or the tag-cap wording.
  • Tests-new: PASS. No new public names. The newly documented behaviour is covered by test_reports_still_queued_at_the_timeout_are_sent_after_close_returns.
  • Tests-fix: N/A. No production logic changed. The new test checks current behaviour.
  • Sibling structure / renames: PASS. No new files and no renames.
  • Docs: PASS. The README promises table and the close() docstring now agree with close() as written (a thread.join(timeout) with no cancellation). The tag-cap line matches _with_install's len(tags) >= MAX_TAGS check, which runs after version is merged in.
  • Issue resolution: N/A. No Closes; this came from the documentation sweep.
  • CI: PASS. test (3.8), test (3.10) and test (3.12) are green on the PR head.
  • Stdlib-only: PASS. The diff adds no import lines.
  • Py3.8 floor: PASS. test (3.8) is green, and the local run was also on 3.8.10 (78 tests, OK).
  • Never-raises / never-blocks: PASS. The only change under trace_client/ is a docstring.
  • Log level: PASS. The diff adds no _LOG calls.
  • Version agreement: PASS. The version is untouched.
  • Exports: PASS. No new public names.
  • Java parity noted: PASS. The PR body says no Java-visible behaviour changed and that the Java docs could not be checked this session.

Judgment notes:

  • trace_client/trace_client.py:296 — the docstring still opens with "Stop the sending thread". Read with the new sentence it is accurate (the thread does stop once it reaches the sentinel). Rewording the opening line was left out to keep the diff small.
  • tests/test_trace_client.py — the new test's is_alive() assertion holds because the loopback server holds the request until release is set, and the client's 5 s socket timeout is longer than the 0.5 s close() timeout. The timing margin is several seconds.

Summary: a docs-only correction with a characterization test. CI is green and no do-not-auto-merge path is touched.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit 07410b9 into main Nov 14, 2026
3 checks passed
@dmccoystephenson
dmccoystephenson deleted the trace/close-timeout-docs branch November 14, 2026 02:50
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