fix: silence telemetry network errors in firewalled environments

[TabishB]

Summary

• Wraps PostHog's fetch with safeTelemetryFetch that catches all network errors and non-2xx responses, returning a synthetic 204 — PostHog never throws PostHogFetchNetworkError
• Disables retries (fetchRetryCount: 0), remote config, surveys, and feature flag preloading to eliminate extra network calls; adds 1s request timeout
• Documents OPENSPEC_TELEMETRY and DO_NOT_TRACK env vars in the CLI reference table
• Updates docs/cli.md config examples to show env-based telemetry opt-out

Closes #895

Test plan

• All 15 telemetry tests pass (5 new tests covering network error, abort, non-2xx, and success passthrough)
• Tests pass with CI=true (simulating GitHub Actions)
• Manual: run openspec init with network blocked — no PostHog errors visible
• Manual: run with OPENSPEC_TELEMETRY=0 — telemetry fully skipped

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added documentation for disabling telemetry via OPENSPEC_TELEMETRY and DO_NOT_TRACK environment variables.

• Bug Fixes

  • Improved telemetry reliability with request timeout and graceful error handling.

[1code-async]

Task completed.

I'll start by reviewing the PR changes to provide constructive feedback.

---

View full conversation

Powered by 1Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 0fc273f9-48ef-4632-a14a-36bf3c8391de

📥 Commits

Reviewing files that changed from the base of the PR and between 802292a and 2872dbf.

📒 Files selected for processing (1)

• docs/cli.md

✅ Files skipped from review due to trivial changes (1)

• docs/cli.md

---

📝 Walkthrough

Walkthrough

Added a safe telemetry fetch wrapper with a 1s timeout and silent-failure behavior, configured PostHog to use it with retries and remote features disabled, updated tests to validate the behavior, and documented environment-variable telemetry disablement (OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1).

Changes

Cohort / File(s)	Summary
Documentation docs/cli.md	Added env var entries documenting telemetry disablement: OPENSPEC_TELEMETRY=0 and DO_NOT_TRACK=1.
Telemetry Infrastructure src/telemetry/index.ts	Added safeTelemetryFetch (1s timeout) that returns original 2xx responses and converts network errors, AbortErrors, and non-2xx responses into a synthetic 204; configured PostHog to use this fetch, fetchRetryCount: 0, requestTimeout: 1000, and disabled preload/remote config/surveys.
Telemetry Tests test/telemetry/index.test.ts	Expanded tests to spy on globalThis.fetch, assert PostHog init settings (host, flushAt, flushInterval, fetchRetryCount, requestTimeout, disabled remote features, and injected fetch), and validate safeTelemetryFetch behavior across success, network error, AbortError, and non-2xx responses.

Sequence Diagram

sequenceDiagram
    participant Client
    participant PostHog as PostHog Client
    participant Fetch as safeTelemetryFetch
    participant Network as Network/API

    Client->>PostHog: Initialize client (custom fetch, timeout=1000, retries=0, disable remote)
    PostHog->>Fetch: Call fetch(url, options)
    Fetch->>Network: fetch(url, options) with 1s timeout

    alt Network Success (2xx)
        Network-->>Fetch: Response { ok: true, status: 200 }
        Fetch-->>PostHog: Return original Response
    else Non-2xx Response
        Network-->>Fetch: Response { ok: false, status: 403 }
        Fetch-->>PostHog: Return synthetic Response { status: 204 }
    else Network/Error/Abort or Timeout
        Network--x Fetch: Throws Error / AbortError / Timeout
        Fetch-->>PostHog: Return synthetic Response { status: 204 }
    end

    PostHog->>PostHog: Continue without retries or remote config

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I hopped a line, I wrapped a call,

Timed a second so none would fall.
When networks grumble, I softly sigh—204—
Quiet and steady, telemetry restored.
🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: silencing telemetry network errors in firewalled environments, which is the core objective of this PR.
Linked Issues check	✅ Passed	The PR fully implements the requirement from issue #895: it wraps PostHog fetch to catch network errors and return synthetic 204 responses, preventing PostHogFetchNetworkError exceptions.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to addressing issue #895: telemetry error handling, timeout configuration, environment variable documentation, and comprehensive tests.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch TabishB/silent-telemetry-errors

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

README.md (1)

108-108: ⚠️ Potential issue | 🟡 Minor

Keep support-count messaging consistent across README.

Line 108 says “25+ tools,” but Line 131 still says “20+ AI assistants.” Please align these to avoid contradictory claims in the same document.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 108, Update the README to make the support-count messaging
consistent: replace the conflicting phrase "20+ AI assistants" so it matches
"25+ tools" (or vice versa) wherever the text currently uses "25+ tools" and
"20+ AI assistants" — search for those exact strings and standardize to a single
agreed count, updating any related wording like "tools" vs "AI assistants" so
both occurrences (the lines containing "25+ tools" and "20+ AI assistants")
convey the same, non-contradictory message.

🧹 Nitpick comments (1)

docs/cli.md (1)

789-793: Move telemetry init examples out of the openspec config examples block.

These are openspec init usage examples, so they read as out-of-place in this subsection.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/cli.md` around lines 789 - 793, The two telemetry examples using
OPENSPEC_TELEMETRY and DO_NOT_TRACK belong under the openspec init usage
section, not inside the openspec config examples block; move the lines
"OPENSPEC_TELEMETRY=0 openspec init" and "DO_NOT_TRACK=1 openspec init" out of
the current config subsection and place them into the openspec init
examples/usage subsection so they align with the init command examples and
remove them from the config block.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/cli.md`:
- Around line 822-823: Add the two new telemetry environment variables to the
Environment Variables table: document OPENSPEC_TELEMETRY and DO_NOT_TRACK,
describe their accepted values (e.g., OPENSPEC_TELEMETRY=0 to disable, 1 to
enable; DO_NOT_TRACK=1 to opt-out), note that they must be set before first run
in restricted/firewalled environments, and include a short example usage line
showing how to disable telemetry (e.g., OPENSPEC_TELEMETRY=0) so users can find
and use these settings alongside the other variables in the table.

---

Outside diff comments:
In `@README.md`:
- Line 108: Update the README to make the support-count messaging consistent:
replace the conflicting phrase "20+ AI assistants" so it matches "25+ tools" (or
vice versa) wherever the text currently uses "25+ tools" and "20+ AI assistants"
— search for those exact strings and standardize to a single agreed count,
updating any related wording like "tools" vs "AI assistants" so both occurrences
(the lines containing "25+ tools" and "20+ AI assistants") convey the same,
non-contradictory message.

---

Nitpick comments:
In `@docs/cli.md`:
- Around line 789-793: The two telemetry examples using OPENSPEC_TELEMETRY and
DO_NOT_TRACK belong under the openspec init usage section, not inside the
openspec config examples block; move the lines "OPENSPEC_TELEMETRY=0 openspec
init" and "DO_NOT_TRACK=1 openspec init" out of the current config subsection
and place them into the openspec init examples/usage subsection so they align
with the init command examples and remove them from the config block.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 253cd9f4-87c3-4490-971a-4f1568cf25aa

📥 Commits

Reviewing files that changed from the base of the PR and between 9b5007d and b1aca08.

📒 Files selected for processing (5)

• README.md
• docs/cli.md
• docs/installation.md
• src/telemetry/index.ts
• test/telemetry/index.test.ts

[alfred-openspec]

Looks good. The fetch wrapper plus the bounded PostHog settings address the real firewalled-environment failure mode, and the added coverage hits the important cases. I still want a small follow-up for the stale openspec config set telemetry.enabled false workaround in issue #895/docs, but that is separate from this fix.