Skip to content

Log and document the report close() drops from a full queue - #43

Merged
dmccoystephenson merged 1 commit into
mainfrom
trace/log-close-full-queue-drop
Nov 15, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
trace/log-close-full-queue-drop

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

  • close() on a full queue removes the oldest queued report to make room for the stop sentinel. That drop was the only one not logged. It is now logged at DEBUG on the trace logger as [trace] queue full at close, dropped <body>, which matches the README's promise that drops are "logged at DEBUG on the trace logger, otherwise not at all".
  • The close() docstring and the README's "close() drains" row now say that a full queue costs the oldest queued report. Before this, both said only that queued reports get the timeout to be sent and are not discarded.
  • A regression test was added: test_the_report_close_drops_from_a_full_queue_is_logged_at_debug.

Closes #42

Test plan

  • python3 -m unittest: 79 tests ran, OK (local, Python 3)
  • Stash-and-run: with the trace_client.py change stashed, the new test FAILS; with it restored, the test PASSES
  • CI test (3.8), test (3.10), test (3.12) green

Java parity

No Java-visible behavior changed. The change is a local DEBUG log line plus documentation. The wire format, opt-out values and disabled_reason strings are untouched.

Deferred

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

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

Copy link
Copy Markdown
Member Author

Self-review rubric (scored against the diff and command output):

  • Scope: PASS. Three files changed (README row, the close() branch and docstring, one new test), all named by close() on a full queue drops the oldest report without logging or documenting it #42. 29 insertions, 4 deletions.
  • Tests-new: PASS. No new public names. The new log path is exercised by test_the_report_close_drops_from_a_full_queue_is_logged_at_debug.
  • Tests-fix: PASS. Stash-and-run was performed locally: with the trace_client/trace_client.py change stashed, the new test reported FAILED (failures=1); with it restored, OK.
  • Sibling structure: PASS. No new files. The test follows the setup of the neighbouring test_close_on_a_full_queue_drops_the_oldest_report_and_still_stops_the_sender (hold the sender, wait for the queue to empty, fill it).
  • Sibling renames: PASS. Nothing renamed.
  • Docs: PASS. The README "close() drains" row and the close() docstring both now state the full-queue drop. Logging it makes the "Never raises" row's "drops are logged at DEBUG" claim true for this path. The class docstring's three report() properties are unaffected.
  • Issue resolution: PASS. Both parts of close() on a full queue drops the oldest report without logging or documenting it #42 (the missing log line, the missing documentation) are changed.
  • CI: PASS. test (3.8), test (3.10) and test (3.12) are green on head 0c5708f.
  • Stdlib-only: PASS. The diff adds no imports, and pyproject.toml is untouched.
  • Py3.8 floor: PASS. test (3.8) is green.
  • Never-raises / never-blocks: PASS. The change is in close() only, not report()/_send(). The added _LOG.debug sits inside the existing try and adds no wait. A handler error inside logging goes to Handler.handleError, so it cannot propagate.
  • Log level: PASS. The only added _LOG call is _LOG.debug("[trace] queue full at close, dropped %s", dropped).
  • Version agreement: PASS. No version string touched.
  • Exports: PASS. No public names added.
  • Java parity noted: PASS. The PR body states that no Java-visible behaviour changed.

Judgment note: trace_client/trace_client.py:318 logs the dropped body (bytes repr), not just the event name as report()'s queue-full line does. This was chosen deliberately: the body is the only data available at that point without parsing JSON, and _drain/_send already log bodies the same way. It is not treated as blocking.

No FAIL items remain. Do-not-auto-merge paths (workflows, pyproject.toml, version strings, wire format, opt-out values, LICENSE, any file with more than 50 lines deleted): none touched.

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


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit ab24e8d into main Nov 15, 2026
3 checks passed
@dmccoystephenson
dmccoystephenson deleted the trace/log-close-full-queue-drop branch November 15, 2026 07:05
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.

close() on a full queue drops the oldest report without logging or documenting it

1 participant