docs: plain README, and fix the code where it didn't match

[abrichr]

Summary

This PR rewrites the README for a developer who finds openadapt-telemetry on GitHub or PyPI. It also fixes the places where the code didn't do what the old README promised.

README

• The first screen says what the package sends, who it is for, and how to turn it off. It then gives a quick start (install, set a DSN, report an exception) and a doctest that shows the filter working without a DSN.
• "Turn it off" lists the four opt-outs and their order of precedence. The pyproject.toml opt-out from 0.3.0 was missing from the old README.
• "What is sent" is a single table covering error reports and usage events. It now includes what the Sentry SDK collects on its own (log lines, HTTP request URLs, installed packages).
• Limits are in one short section: the pattern scrubbing misses names and free text, URL paths are kept, and the servers see the IP address of each connection.
• The failure-signal example and its boundary statement, internal-usage tagging, and the full filter rules moved to docs/COMPLIANCE.md, which the README links once.
• The first screen addresses people whose OpenAdapt packages depend on this one (pip show lists them), since the openadapt launcher and engine don't. It defines DSN and says that usage events go to OpenAdapt's PostHog project unless another is named.
• The decorator section says that track_performance sends 1% of calls by default, track_feature sends a message event per call, and a TelemetrySpan outside a transaction sends nothing.
• tests/test_readme.py runs the README's examples. The quick start runs against an in-memory Sentry transport, and the message GlitchTip would receive must match the one the README quotes. The test also runs the no-DSN case, the doctest, the usage event, the decorators and the failure-signal example in the docs. It fails if process terms such as "admitted" or "signed ledger" come back.

Code fixes

I pointed a real client at a local HTTP sink and compared what it sent with what the README claimed:

• One opt-out rule. Before this PR, the pyproject.toml opt-out stopped usage events but not error reports. "enabled": false in the config file stopped error reports but not usage events. DO_NOT_TRACK=yes stopped only usage events. Both paths now call is_telemetry_allowed().
• Error reports. The host name (server_name), the full command line (sys.argv), local variable values and source lines were all sent. Transactions skipped the privacy filter entirely. Log-call arguments (logentry.params) were sent raw, and so were HTTP query strings. All of these are now removed or scrubbed. Before, the filter also replaced trace_id with [REDACTED], which broke the link between errors and traces.
• Usage events. Property values are now scrubbed, not only their keys.
• Dependencies. The code needs sentry-sdk 2.15: track_errors raised AttributeError on older SDKs, and so did every TelemetrySpan. The floor is now 2.15.0, and CI also runs the tests against 2.15.0. On Python 3.10, the pyproject.toml opt-out was ignored unless tomli happened to be installed. tomli is now a dependency for Python versions before 3.11.
• Deprecated calls. push_scope, set_measurement, the explicit send_default_pii and datetime.utcnow are replaced. The suite passes with DeprecationWarning treated as an error.
• Config file. "internal": true in the config file now tags reports as internal. It was read but ignored.
• Repository. Twelve tracked __pycache__/*.pyc files are removed and now ignored.
• Release. initialize() didn't set a release, so the SDK sent the commit hash of whatever git checkout the process ran in. The release is now <package_name>@<package_version>, and a caller can still pass release=.

Testing

• pytest -W error::DeprecationWarning: 168 passed on Python 3.12 with sentry-sdk 2.72.0, and on Python 3.10 with sentry-sdk 2.15.0.
• I simulated the CI steps (uv sync --extra dev, ruff, pytest, then pytest again with sentry-sdk 2.15.0) in a clean copy. All passed.
• I built a wheel and sdist with uv build, and twine check passes. In a fresh Python 3.11 venv with the wheel installed, I ran the README quick start against a local HTTP sink. It received FileNotFoundError: [Errno 2] No such file or directory: '/Users/<user>/notes.txt' with no server_name, no sys.argv, and frames that hold only file, function, line, module and in_app. Without a DSN, initialize() returned False.
• In a fresh Python 3.10 venv with the wheel installed, is_telemetry_allowed() returns False under a pyproject.toml that opts out. It returned True before the tomli dependency was added.
• I followed the quick start from a fresh venv against a local HTTP server, from a plain directory and from inside a git checkout. Both sent one request with the quoted message and release mypackage@0.1.0. The four opt-outs each sent nothing. The usage-event example, run as written, sent nothing because the process exits before the background thread posts; the README now says so.
• The prospect-name guard is clean.

Notes

• Merging to main runs the semantic-release workflow. The fix: commits make that a patch release, which is also what updates the README on PyPI. The README describes the behavior after this PR, so the published 0.3.1 still has the gaps listed above until that release.
• Not changed: the config keys error_tracking, performance_tracking and feature_usage are saved and loaded but nothing reads them. The README doesn't mention them.

🤖 Generated with Claude Code