Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

5.2 KB
Raw Blame
#!/usr/bin/env python3
"""Best-effort usage telemetry for the toolbox CLI.

Sends a single event per invocation via the PostHog Python SDK (``posthog``, see
https://posthog.com/docs/libraries/python). The SDK is a declared dependency of
this tool (see ``requirements.txt``); if it isn't installed the capture degrades
to a no-op. Every failure is swallowed — telemetry must never delay or break
connecting to a pod. The project API key embedded here is a write-only ingestion
key (the same kind shipped in client SDKs), overridable per-environment via
``TOOLBOX_POSTHOG_API_KEY`` / ``TOOLBOX_POSTHOG_HOST``.
"""

import os
import sys
import platform

# Write-only project API key. Safe to embed; override per-environment with the env var.
DEFAULT_API_KEY = "sTMFPsFhdP1Ssg"
DEFAULT_HOST = "https://us.i.posthog.com"

EVENT_NAME = "toolbox cli used"

# The free-text reason is also submitted as a PostHog API-type survey response so
# it lands in the Surveys UI (response browsing + AI summary). Create an API-type
# survey with one open-text question in PostHog, then set SURVEY_ID (or the env var
# below). For a single-question survey the `$survey_response` shorthand binds to the
# first question, so no per-question id is needed. Left empty, the survey submission
# is skipped and only EVENT_NAME fires.
# https://posthog.com/docs/surveys/implementing-custom-surveys
SURVEY_ID = "019ecbd7-19cd-0000-0adf-226a0612404f"
SURVEY_QUESTION_TEXT = "What are you using the toolbox for today?"


def prompt_for_reason() -> str:
    """Ask the user what they're using the toolbox for.

    Skipped when stdin isn't a TTY (CI, piped input, --auto-delete automation) so
    it never blocks a non-interactive run. Returns "" when skipped or on EOF/Ctrl-C.
    """
    if not sys.stdin.isatty():
        return ""
    try:
        return input(f"📝 {SURVEY_QUESTION_TEXT} (press Enter to skip): ").strip()
    except (EOFError, KeyboardInterrupt):
        # Don't let an empty/aborted answer derail the run; a Ctrl-C here just skips the question.
        return ""


def _capture_survey_response(client, distinct_id: str, answer: str) -> None:
    """Submit the free-text reason as a PostHog API-type survey response.

    No-op unless the survey id is configured and the user gave an answer, so an
    unconfigured survey or a skipped prompt never emits a half-formed event.
    """
    survey_id = os.environ.get("TOOLBOX_SURVEY_ID", SURVEY_ID)
    if not (survey_id and answer.strip()):
        return

    client.capture(
        event="survey sent",
        distinct_id=distinct_id,
        properties={
            "$survey_id": survey_id,
            # Single-question survey: `$survey_response` binds to the first question.
            "$survey_response": answer,
            "$survey_questions": [{"question": SURVEY_QUESTION_TEXT}],
        },
    )
    print(f"📊 Telemetry: submitted survey response to survey {survey_id}")  # noqa: T201


def capture_invocation(distinct_id: str, properties: dict) -> None:
    """Fire a single best-effort capture event via the PostHog SDK. Never raises."""
    api_key = os.environ.get("TOOLBOX_POSTHOG_API_KEY", DEFAULT_API_KEY)
    host = os.environ.get("TOOLBOX_POSTHOG_HOST", DEFAULT_HOST)
    if not api_key or api_key == "phc_REPLACE_ME":
        # No real key configured — stay silent rather than spamming a dead endpoint.
        print("📊 Telemetry skipped: no PostHog API key configured.")  # noqa: T201
        return

    try:
        # Imported lazily so a missing SDK degrades to a no-op instead of breaking
        # the import of this module. Install with `pip install -r requirements.txt`.
        try:
            from posthog import (
                Posthog,  # type: ignore[import-not-found]  # noqa: PLC0415 — optional dep, kept off the import path
            )
        except ImportError:
            # The repo's flox venv has the same SDK, published as `posthoganalytics` instead of `posthog`.
            from posthoganalytics import Posthog  # noqa: PLC0415 — optional dep, kept off the import path

        resolved_distinct_id = distinct_id or "unknown"
        # shutdown() below blocks before the pod claim, and the SDK defaults (15s timeout, 3 retries) can hold it for over a minute.
        client = Posthog(project_api_key=api_key, host=host, timeout=2, max_retries=0)
        client.capture(
            event=EVENT_NAME,
            distinct_id=resolved_distinct_id,
            properties={
                **properties,
                "os": platform.system(),
                "os_release": platform.release(),
                "python_version": platform.python_version(),
            },
        )
        print(f"📊 Telemetry: sent '{EVENT_NAME}' event to {host}")  # noqa: T201

        _capture_survey_response(client, resolved_distinct_id, properties.get("usage_reason", ""))

        # Synchronous flush so events aren't lost when the long-lived shell session ends.
        client.shutdown()
    except ImportError:
        print("📊 Telemetry skipped: posthog SDK not installed (pip install -r requirements.txt).")  # noqa: T201
    except Exception as telemetry_error:
        # Best-effort only; never let a send failure block connecting to a pod.
        print(f"📊 Telemetry failed (ignored): {telemetry_error}")  # noqa: T201