feat: add PostHog event tracking for SDK installs (ENG-2277)

[devin-ai-integration]

Summary

Adds lightweight PostHog event tracking to the Python SDK to fire an "Installed SDK" event once per new SDK version. Mirrors the existing Sentry pattern — no external PostHog library, uses httpx (already a dependency) for a raw HTTP POST to https://us.i.posthog.com/capture/.

How it works:

• track_sdk_installed() is called during autoload() (gated behind settings.tracking)
• Deduplicates via ~/.blaxel/telemetry.json — only fires once per SDK version
• Fire-and-forget on a daemon thread with 5s timeout; all exceptions silently swallowed
• __posthog_key__ placeholder in __init__.py is injected at build time via sed in CI (same pattern as __sentry_dsn__)
• Anonymous UUID v4 as distinct_id, persisted in telemetry.json

Review & Testing Checklist for Human

• Provision POSTHOG_KEY secret in the repo's release environment before the next release — without it, tracking is silently disabled (no build failure)
• Verify circular import safety: posthog.py does import blaxel inside _get_posthog_key() which is called from track_sdk_installed() during autoload(), itself called from blaxel.__init__. The lazy call timing should be safe (same pattern as settings.sentry_dsn), but worth a manual python -c "import blaxel.core" check
• Verify telemetry.json concurrent access is acceptable: no file lock is used when reading/writing the shared state file — concurrent CLI + SDK runs could race, but worst case is a duplicate event (matches existing CLI pattern)
• Test sed injection end-to-end: after CI runs, confirm __posthog_key__ in the built package is replaced with the actual key value

Notes

• httpx is already a core dependency — no new packages added
• telemetry.json is shared between CLI and all SDKs (Python, TypeScript) — the sdks.python key tracks the last reported Python SDK version
• Tracking is opt-in (settings.tracking defaults to False), consistent with the existing Sentry behavior

Link to Devin session: https://app.devin.ai/sessions/43a6073c1fe54dbfb87b42e3dc01db56
Requested by: @Grotoma

---

---

Note

Adds a new commit that makes telemetry delivery reliable: state is now only persisted to disk after PostHog confirms receipt (via an on_complete callback), with in-memory deduplication using _pending_sdk_versions to prevent concurrent duplicate sends. Comprehensive tests cover delivery failure retry, deduplication, and state preservation.

^{Written by Mendral for commit 18db14c.}

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.

[devin-ai-integration]

❌ Cannot revive Devin session - the session is too old. Please start a new session instead.

[mendral-app]

🧪 Testing Guide

What this PR addresses

Adds lightweight PostHog event tracking to the Python SDK that fires an "Installed SDK" event once per new SDK version. It uses httpx (existing dependency) for a raw HTTP POST to PostHog's capture endpoint. Events are deduplicated via ~/.blaxel/telemetry.json and sent fire-and-forget on a daemon thread.

Steps to reproduce / exercise the new behavior

1. Run the new unit tests:

   pytest tests/core/test_posthog.py -v

   These cover: payload schema validation, failed delivery retry behavior, deduplication logic, and state file preservation.

2. Manual integration check (optional):

   • Ensure ~/.blaxel/telemetry.json does not contain a "python" key under "sdks" (or delete the file).
   • Set DO_NOT_TRACK env var to false (or leave unset).
   • Import and call autoload() from blaxel:

     from blaxel import autoload
     autoload()

   • Verify ~/.blaxel/telemetry.json now contains "sdks": {"python": "<version>"}.
   • Call autoload() again and confirm no duplicate HTTP request is made (version is already recorded).

3. Verify opt-out is respected:

   • Set DO_NOT_TRACK=1 in your environment, clear telemetry state, and call autoload().
   • Confirm no network call is attempted and telemetry state is unchanged.

What to verify (expected behavior)

• ✅ All tests in tests/core/test_posthog.py pass.
• ✅ The POSTHOG_KEY secret is injected at build time via sed in both dev.yaml and prod.yaml CI workflows (mirrors the existing SENTRY_DSN pattern).
• ✅ __posthog_key__ placeholder in src/blaxel/__init__.py is empty by default and only populated during CI builds.
• ✅ Telemetry never breaks SDK functionality — all PostHog code is wrapped in try/except with silent failures.
• ✅ Deduplication works correctly: event fires only once per SDK version, retries on failed delivery, and concurrent calls don't produce duplicates.
• ✅ Existing telemetry state fields (e.g., cli, future_field) are preserved when writing the python SDK version.
• ✅ File permissions on telemetry.json are set to 0o600 (user-only read/write).
• ✅ settings.tracking and DO_NOT_TRACK env var are both respected as opt-out mechanisms.

Note

Posted by PR Testing Guide · Tag @mendral-app with feedback.