Add a debug switch that prints every telemetry event to the terminal and does not send it. Next.js uses an environment variable for this, and Homebrew has one that prints the request. Users and security reviewers can then see the exact payload before deciding whether to leave telemetry on.
What the two projects do
Both documents are public, so you can check them.
Next.js documents that setting NEXT_TELEMETRY_DEBUG=1 means data will not be sent. The data is printed to the standard error stream, prefixed with [telemetry]. It shows a sample event with an event name and a small payload.
Homebrew documents HOMEBREW_ANALYTICS_DEBUG=1, which prints the analytics request for one command. It also says debug mode sends the request synchronously, discards the server response, and is not an opt-out mechanism.
That last point matters. The two are different behaviours, and your docs should say which one you built.
Two designs for a debug switch
| Design | What it does | Good for |
|---|---|---|
| Dry run | Prints the event, does not send | Reviewers who want proof of no egress |
| Print and send | Prints the request and also sends it | Debugging the pipeline itself |
For a trust story, the dry run is the stronger one. A reviewer can run the tool offline with the switch on and see the same events that would otherwise leave.
Steps to build it
- Route every event through one function. If events are emitted from many places, a reviewer cannot be sure the printout is complete.
- Put the debug check inside that function, before the network call, so no code path can send while the flag is on.
- Print the final serialized payload, not a friendly summary. What you print must be byte for byte what you would send.
- Write to stderr, not stdout, so the output does not break scripts that parse your tool's results.
- Name the variable in your telemetry page and in the CLI help.
- Add a test that sets the flag and asserts the network client was never called.
What to publish beside it
Pair the switch with a short page listing the fields collected, why, how long they are kept, and how to opt out. Homebrew's page states a retention period and a list of fields. Next.js lists the fields and says what it does not collect, such as environment variables, file paths, file contents and logs. A statement of exclusions is as useful to a security reader as the list of inclusions.
A common failure
Teams add a debug switch to the main telemetry call and forget the second path, such as a crash reporter or an update check that also sends an identifier. Search your codebase for every outbound request your CLI can make. Telemetry is rarely the sole one.
Quick check
Is a debug flag the same as an opt-out?
No. Homebrew states this directly: its debug mode is not an opt-out mechanism. Provide a separate setting that actually disables collection.
Should the debug output go to stdout?
Use stderr. Scripts often parse stdout, and mixing telemetry lines into it can break them.
If you want a view of what your tool's dependency tree pulls in, including any analytics libraries, Safeguard's free scan at gold.safeguard.sh/scan produces a dependency inventory.
Sources
Last reviewed: 19 October 2026.
