Skip to content

telemetry: document env var, add --no-telemetry flag#2519

Closed
staylor wants to merge 1 commit into
lightpanda-io:mainfrom
staylor:telemetry/document-and-cli-flag
Closed

telemetry: document env var, add --no-telemetry flag#2519
staylor wants to merge 1 commit into
lightpanda-io:mainfrom
staylor:telemetry/document-and-cli-flag

Conversation

@staylor
Copy link
Copy Markdown
Contributor

@staylor staylor commented May 21, 2026

Problem

LIGHTPANDA_DISABLE_TELEMETRY already opts out of telemetry, but:

  • It is missing from lightpanda --help (any subcommand).
  • The README only mentions it in one sentence and shows it as =true, which suggests the value matters — it does not. The current implementation uses std.process.hasEnvVarConstant, so the variable just needs to be present (any value, including empty).
  • There is no CLI equivalent, so users who do not want to set environment variables (CI configs, one-off invocations, MCP launchers) have no way to opt out.

Changes

  • Add --no-telemetry as a common option for serve, fetch, and mcp. Wired into the existing CommonOptions block in Config.zig so it picks up the standard --kebab-case / --snake_case handling and unknown-flag validation for free.
  • Make the crash reporter honor the flag. crash_handler.zig calls telemetry.isDisabled() from a panic context where the App/Config are not reachable, so I added a module-level cli_disabled flag + setDisabledByCli setter that App.init populates from config.noTelemetry() before Telemetry.init runs. This guarantees --no-telemetry suppresses crash reports too.
  • Document both opt-outs. src/help.zon now lists --no-telemetry under common options and references the env var. The README clarifies that the env var only needs to be present (no specific value required) and that debug builds always disable telemetry.
  • Extend the existing telemetry test to assert that the CLI override path also short-circuits isDisabled().

Verification

zig fmt --check ./*.zig ./**/*.zig    # clean
make test                              # 720 of 720 tests passed

./zig-out/bin/lightpanda help fetch | grep -A4 no-telemetry
  --no-telemetry
          Disable anonymous usage telemetry and crash reporting.
          Equivalent to setting the LIGHTPANDA_DISABLE_TELEMETRY
          environment variable (any value, including empty).
          See https://lightpanda.io/privacy-policy for details.

./zig-out/bin/lightpanda fetch http://example.com --no-telemetryX
FATAL app : unknown argument
      mode = fetch
      arg = --no-telemetryX

Notes

  • No existing behavior changes when neither the flag nor env var is set.
  • The semantics of LIGHTPANDA_DISABLE_TELEMETRY are unchanged; only its documentation is updated to match the actual implementation.
  • Debug/test builds remain hard-disabled, matching the prior invariant covered by telemetry: always disabled in debug builds.

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 21, 2026

All contributors have signed the CLA ✍️ ✅
Posted by the CLA Assistant Lite bot.

The LIGHTPANDA_DISABLE_TELEMETRY environment variable already opted out
of telemetry but was missing from --help and only mentioned briefly in
the README.

This commit:

- Adds a --no-telemetry common option (works for serve, fetch, and mcp).
- Threads a CLI override into telemetry.isDisabled() so the crash
  reporter, which runs outside the App lifecycle, also honors the flag.
- Documents both opt-outs in help.zon and the README, and clarifies
  that LIGHTPANDA_DISABLE_TELEMETRY treats any value (including empty)
  as truthy — the env var only needs to be present.
- Extends the debug-build telemetry test to cover the CLI override.
@staylor staylor force-pushed the telemetry/document-and-cli-flag branch from 4ebf806 to 9c092ea Compare May 21, 2026 18:44
@karlseguin
Copy link
Copy Markdown
Collaborator

I do like that this is more discoverable. My only reservation is that there's a window (before App.init is called) where the flag is ignored. So it would be possible for --no-telemetry to be set but a crash report would still happen. I assume this is likely common. Punting this one to @krichprollsch also.

@krichprollsch
Copy link
Copy Markdown
Member

Thanks for the contribution. After discussion and while we understand your points, as an open source project, telemetry is vital to sustaining development in the long run. That's why we prefer to close this change and keep only the env var for now.

There is no CLI equivalent, so users who do not want to set environment variables (CI configs, one-off invocations, MCP launchers) have no way to opt out.

For CI config it's common to setup env vars, we do that ourself.

On-off invocation is also quite easy to do: LIGHTPANDA_DISABLE_TELEMETRY=true lightpanda

And in mcp configuration, for example, with Claude you can setup env vars easily.

So IMO the env var is well supported and good enough in all these cases.

@github-actions github-actions Bot locked and limited conversation to collaborators May 22, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants