Skip to content

fix: pass the usage-reporting opt-outs and overrides through compose - #261

Merged
dmccoystephenson merged 1 commit into
mainfrom
feature/compose-usage-reporting-passthrough
Nov 6, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
feature/compose-usage-reporting-passthrough

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

  • compose.yml names the viron service's environment one variable at a time and has no env_file, so a variable it does not name never reaches the container. DO_NOT_TRACK=1 and TRACE_USAGE_REPORTING=off therefore had no effect under the documented docker-compose up, although the README lists both as ways to turn reporting off. TRACE_INSTALL_ID, USAGE_REPORTING_ENDPOINT and USAGE_REPORTING_KEY had the same gap.
  • All five are now declared on the service without a value, so Compose passes each one only when it is set and leaves it unset in the container otherwise.
  • sample.env lists all five, commented out. The README states what is passed through and warns that an empty endpoint or key turns reporting off.

Closes #258

Why no default values

The issue noted that empty is not the same as unset for the endpoint and key. That was confirmed in the source. USAGE_REPORTING_KEY= set but empty gives REASON_NO_KEY, and USAGE_REPORTING_ENDPOINT= set but empty makes the builder throw, which UsageReporter.buildClient turns into a disabled client. A ${VAR:-} entry, the form used for other optional variables in this file, would therefore have switched reporting off for every default deployment. A real default would have copied the bundled key into compose.yml. A key-only entry avoids both and keeps today's behaviour when nothing is set.

An operator who explicitly sets the endpoint or key to an empty value in .env still turns reporting off. This is documented in the README and in sample.env.

Test plan

  • mvn -B test: 663 tests run, 0 failures, 0 errors, 0 skipped.
  • New ComposeUsageReportingTest parses the real compose.yml and sample.env. With those two files reverted, both of its tests fail (Tests run: 2, Failures: 2). With the fix restored, both pass.
  • Not verified: docker compose itself. Docker is not available in the session sandbox, so compose.yml was parsed as YAML but never loaded by Compose. The resolution of key-only entries from the shell and from .env rests on the Compose documentation. A smoke test is recommended before merge: run docker compose config with DO_NOT_TRACK=1 in .env and confirm it appears on the viron service, then run it with the variable absent and confirm that USAGE_REPORTING_KEY does not appear.

Merge hold

compose.yml is on the dev loop's do-not-auto-merge list, so this PR is left open for human review even though the run was pre-authorized to merge.

Triage / skip reasons

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


drafted by Claude on behalf of Daniel Stephenson

🤖 Generated with Claude Code

…258)

compose.yml names the viron service's environment one variable at a
time and has no env_file, so DO_NOT_TRACK, TRACE_USAGE_REPORTING,
TRACE_INSTALL_ID, USAGE_REPORTING_ENDPOINT and USAGE_REPORTING_KEY never
reached the container. Under docker-compose, the documented opt-outs
did nothing.

They are declared without a value, so compose passes each only when it
is set. A ${VAR:-} empty string would turn reporting off, because an
empty endpoint or key disables the client rather than falling back to
its default.

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

Copy link
Copy Markdown
Member Author

Self-review rubric (anchored on CI run 41994261520: build, python-client (3.8) and python-client (3.12) all green on head 2bb1d91):

  • Scope: PASS. All four files serve compose.yml drops the usage-reporting opt-outs and TRACE_INSTALL_ID that the README documents #258: the fix, its sample.env and README documentation, and one test class.
  • Tests-new: PASS. No production method is added. The two new tests cover the changed configuration.
  • Tests-fix: PASS. With compose.yml and sample.env stashed, ComposeUsageReportingTest gave Tests run: 2, Failures: 2; with them restored it gave Tests run: 2, Failures: 0. Full suite: Tests run: 663, Failures: 0, Errors: 0, Skipped: 0.
  • Sibling structure: PASS. The test follows UsageReporterEnvironmentTest (package, licence header, AssertJ, class Javadoc) and reads repository files by relative path, as OpenApiSpecDriftTest does.
  • Sibling renames: PASS. Nothing was renamed.
  • Docs: PASS. The README, sample.env and the compose.yml comment describe the new behaviour. docs/MVP.md, docs/PLANNING.md, docs/REBUILD_PLAN.md, tickets.md, .devcontainer/, scripts/ and postman/ do not mention these variables. docs/openapi/viron-api.json is unaffected, as no endpoint changed.
  • Issue resolution: PASS at the YAML level. All five named variables are on the service and in sample.env, and the empty-versus-unset caution is handled.
  • CI: PASS, with a stated limit. All three jobs are green, but no job runs Compose.
  • DTO boundary: PASS. No controller was touched.
  • Spec alignment: PASS. No endpoint was added or changed.
  • Java/Python parallelism: PASS. This is deployment configuration, so neither client is affected.
  • Override correctness: PASS. No @Override was added.

Judgment notes for the human reviewer:

  • compose.yml:44 — the behaviour rests on Compose semantics that were not exercised. The key-only form is documented as leaving an unresolved variable unset, but neither that nor resolution from .env was observed, because Docker is not available in the sandbox. ComposeUsageReportingTest proves only the shape of the file. The docker compose config smoke test in the PR description closes this gap.
  • compose.yml:44 — the key-only entries deliberately differ from the ${VAR:-} style used for the other optional variables in this file. The reason is recorded in the comment above them.
  • src/test/java/preponderous/viron/trace/ComposeUsageReportingTest.java:50 — the sample.env test pins the #NAME= commented-out spelling. Rewording those lines would need a test change. That is accepted, because the commented-out form is what keeps an empty endpoint or key from being copied into .env by accident.
  • Dockerfile:17 builds with -DskipTests and copies only src and pom.xml, so the new test's dependence on compose.yml at the repository root cannot break an image build.

This PR is not auto-merged: compose.yml is on the do-not-auto-merge list. CI is green and the branch is mergeable, so it is ready for human review. Issue #258 stays open until then.

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 f73dcf9 into main Nov 6, 2026
3 checks passed
@dmccoystephenson
dmccoystephenson deleted the feature/compose-usage-reporting-passthrough branch November 6, 2026 01:48
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.

compose.yml drops the usage-reporting opt-outs and TRACE_INSTALL_ID that the README documents

1 participant