pythinker-code 0.8.0__py3-none-any.whl

pythinker_code/telemetry/__init__.py

@@ -0,0 +1,217 @@
+"""
+Telemetry event tracking for pythinker-code.
+
+This module has NO dependencies on other pythinker_code modules to avoid import cycles.
+track() can be called at any point during startup, even before the sink is attached.
+Events are buffered in memory and flushed once the sink is ready.
+
+Usage:
+    from pythinker_code.telemetry import track, set_context, attach_sink
+
+    # Early in startup — events queue in memory
+    track("first_launch")
+
+    # After app init — attach sink to start flushing
+    set_context(device_id="abc", session_id="def")
+    attach_sink(sink)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import time
+import uuid
+from collections import deque
+from contextlib import suppress
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pythinker_code.telemetry.sink import EventSink
+
+# ---------------------------------------------------------------------------
+# Module-level state (zero dependencies)
+# ---------------------------------------------------------------------------
+
+_MAX_QUEUE_SIZE = 1000
+"""Maximum number of events to buffer before sink is attached."""
+
+_event_queue: deque[dict[str, Any]] = deque(maxlen=_MAX_QUEUE_SIZE)
+"""Events buffered before sink is attached."""
+
+_device_id: str | None = None
+_session_id: str | None = None
+_client_info: tuple[str, str | None] | None = None
+"""(name, version) tuple, set atomically via set_client_info."""
+_MAX_SESSION_STARTED_CACHE = 1024
+_session_started_sessions: set[str] = set()
+_session_started_order: deque[str] = deque()
+"""Bounded session ids that already emitted the session_started event in this process."""
+_sink: EventSink | None = None
+_disabled: bool = False
+
+
+def set_context(*, device_id: str, session_id: str) -> None:
+    """Set device and session identifiers. Call once after app init."""
+    global _device_id, _session_id
+    _device_id = device_id
+    _session_id = session_id
+
+
+def set_client_info(*, name: str, version: str | None = None) -> None:
+    """Set the wire/acp client name and version (e.g. VSCode 1.90.0, zed 0.180.0).
+
+    Called by wire/acp servers after receiving the client's initialize message.
+    Values are passed through verbatim — backend is responsible for any
+    validation, normalization or alerting on anomalous values.
+    """
+    global _client_info
+    if not name:
+        return
+    _client_info = (name, version)
+
+
+def get_client_info() -> tuple[str, str | None] | None:
+    """Return the current (name, version) tuple, or None if unset.
+
+    Used by session-level telemetry to attribute wire/acp sessions.
+    """
+    return _client_info
+
+
+def track_session_started_once(
+    *,
+    ui_mode: str,
+    resumed: bool,
+    client_name: str | None = None,
+    client_version: str | None = None,
+) -> None:
+    """Emit one session_started event for the current session in this process."""
+    session_id = _session_id
+    if not session_id or session_id in _session_started_sessions:
+        return
+
+    ui = (ui_mode or "unknown").strip().lower()
+    name = client_name
+    version = client_version
+    if name is None and ui in {"wire", "acp"}:
+        client_info = get_client_info()
+        if client_info is not None:
+            name, version = client_info
+    if not name:
+        name = ui or "unknown"
+
+    _session_started_sessions.add(session_id)
+    _session_started_order.append(session_id)
+    while len(_session_started_order) > _MAX_SESSION_STARTED_CACHE:
+        expired = _session_started_order.popleft()
+        _session_started_sessions.discard(expired)
+    track(
+        "session_started",
+        client_name=name,
+        client_version=version,
+        ui_mode=ui,
+        resumed=resumed,
+    )
+
+    if _sink is not None:
+        with suppress(Exception):
+            asyncio.get_running_loop().create_task(_sink.flush())
+
+
+def disable() -> None:
+    """Permanently disable telemetry for this process. Events are silently dropped."""
+    global _disabled
+    _disabled = True
+    _event_queue.clear()
+    if _sink is not None:
+        _sink.clear_buffer()
+
+
+def attach_sink(sink: EventSink) -> None:
+    """Attach the event sink and drain any queued events.
+
+    Multi-session ACP mode calls ``PythinkerCLI.create()`` per session, which
+    means ``attach_sink`` runs again while a previous sink may hold
+    un-flushed buffered events. Flush the old sink synchronously (writes
+    any pending events to the disk fallback) before replacing it, so
+    earlier sessions' events are not silently orphaned.
+    """
+    global _sink
+    if _sink is not None and _sink is not sink:
+        # flush_sync already swallows its own transport failures;
+        # ``suppress`` guards against truly unexpected errors so sink
+        # replacement is never blocked by a flaky predecessor.
+        with suppress(Exception):
+            _sink.flush_sync()
+    _sink = sink
+    # Drain events that were queued before sink was ready,
+    # backfilling device_id/session_id for events tracked before set_context().
+    if _event_queue:
+        for event in _event_queue:
+            if event.get("device_id") is None:
+                event["device_id"] = _device_id
+            if event.get("session_id") is None:
+                event["session_id"] = _session_id
+            _sink.accept(event)
+        _event_queue.clear()
+
+
+def track(event: str, **properties: bool | int | float | str | None) -> None:
+    """
+    Record a telemetry event.
+
+    This function is non-blocking: it appends to an in-memory list.
+    Safe to call from synchronous prompt_toolkit key handlers.
+
+    Args:
+        event: Event name (e.g. "input_command").
+        **properties: Event properties. String values should only be used for
+            known enum-like values (command names, mode names, error types).
+            NEVER pass user input, file paths, or code snippets.
+    """
+    if _disabled:
+        return
+
+    record = {
+        "event_id": uuid.uuid4().hex,
+        "device_id": _device_id,
+        "session_id": _session_id,
+        "event": event,
+        "timestamp": time.time(),
+        "properties": properties if properties else {},
+    }
+
+    if _sink is not None:
+        _sink.accept(record)
+    else:
+        _event_queue.append(record)
+
+
+def get_sink() -> EventSink | None:
+    """Return the current sink, or None if not attached."""
+    return _sink
+
+
+def flush_sync() -> None:
+    """Synchronously flush any buffered events. Called on exit.
+
+    Drains the in-process buffer first (so any pending ``track()`` events get
+    handed to the OTel exporter), then waits for both Sentry and OTel to
+    finish their network round-trips.
+    """
+    if _sink is not None:
+        _sink.flush_sync()
+    # Flush vendor SDKs last — they take the network hit.
+    try:
+        from pythinker_code.telemetry import otel as _otel
+        from pythinker_code.telemetry import sentry as _sentry
+
+        _sentry.flush(timeout_seconds=2.0)
+        _otel.shutdown(timeout_millis=2000)
+    except Exception:
+        pass
+
+
+# Register atexit handler to flush remaining events on normal exit
+atexit.register(flush_sync)

pythinker_code/telemetry/config.py

@@ -0,0 +1,113 @@
+"""Telemetry endpoint configuration.
+
+Defaults point at the pythinker-operated Bugsink + SigNoz infrastructure.
+Sentry/Bugsink DSNs are designed to be public; the OTLP bearer token is embedded
+following the same industry convention used by Datadog RUM and PostHog public
+keys, mitigated server-side by rate limiting and PII scrubbing at the edge
+collector.
+
+Override any value at runtime with the matching environment variable. Telemetry
+is off by default; enable it with ``PYTHINKER_ENABLE_TELEMETRY=1``. Disable
+telemetry explicitly with ``PYTHINKER_DISABLE_TELEMETRY=1``.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# ---------------------------------------------------------------------------
+# Bugsink (Sentry-protocol error tracking)
+# ---------------------------------------------------------------------------
+
+DEFAULT_SENTRY_DSN = "https://ab578ebdf2f24c279d9e866ee190574c@errors.pythinker.com/1"
+
+# ---------------------------------------------------------------------------
+# SigNoz via the pythinker edge OTel collector
+# ---------------------------------------------------------------------------
+
+DEFAULT_OTEL_ENDPOINT = "https://otel.pythinker.com"
+DEFAULT_OTEL_INGEST_TOKEN = "83e2d8f0cb72c6c0f8896b40cf68de6e67bfad895a61729b36bc27e594d66d69"
+
+# ---------------------------------------------------------------------------
+# Resolution
+# ---------------------------------------------------------------------------
+
+
+def sentry_dsn() -> str:
+    """Resolve the Sentry/Bugsink DSN, honoring env override and explicit empty."""
+    return os.environ.get("PYTHINKER_SENTRY_DSN", DEFAULT_SENTRY_DSN)
+
+
+def otel_endpoint() -> str:
+    """Resolve the OTLP HTTP endpoint base URL (no trailing slash)."""
+    return os.environ.get("PYTHINKER_OTEL_ENDPOINT", DEFAULT_OTEL_ENDPOINT).rstrip("/")
+
+
+def otel_ingest_token() -> str:
+    """Resolve the bearer token presented to the edge collector."""
+    return os.environ.get("PYTHINKER_OTEL_TOKEN", DEFAULT_OTEL_INGEST_TOKEN)
+
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def _env_truthy(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in _TRUTHY
+
+
+def is_test_environment() -> bool:
+    """Return True when running under pytest unless explicitly overridden.
+
+    Unit tests deliberately raise synthetic exceptions (``boom``, ``disk full``,
+    cancelled subagents, and so on). Those are useful for local assertions but
+    must never be exported to the production Bugsink/SigNoz projects.
+    """
+    if _env_truthy("PYTHINKER_FORCE_TELEMETRY_IN_TESTS"):
+        return False
+    return "PYTEST_CURRENT_TEST" in os.environ or "pytest" in sys.modules
+
+
+def is_disabled() -> bool:
+    """Master kill switch for external Sentry/OTel emission.
+
+    Telemetry is opt-in: ``PYTHINKER_ENABLE_TELEMETRY=1`` must be set before
+    any external Sentry/OTel emission is attempted. ``PYTHINKER_DISABLE_TELEMETRY=1``
+    remains an explicit kill switch, and pytest is treated as disabled by default
+    so test suites cannot leak deliberate test failures to production telemetry
+    backends.
+    """
+    if _env_truthy("PYTHINKER_DISABLE_TELEMETRY"):
+        return True
+    if is_test_environment():
+        return True
+    return not _env_truthy("PYTHINKER_ENABLE_TELEMETRY")
+
+
+# ---------------------------------------------------------------------------
+# Sampling
+# ---------------------------------------------------------------------------
+
+DEFAULT_OTEL_TRACE_SAMPLE_RATE = 1.0
+"""Default fraction of root-trace spans to record. 1.0 = always-on; 0.0 = none."""
+
+
+def otel_trace_sample_rate() -> float:
+    """Resolve the OTel trace sampling rate.
+
+    Honors ``PYTHINKER_OTEL_TRACE_SAMPLE_RATE``. Clamped to ``[0.0, 1.0]``.
+    Malformed input falls back to the default rather than disabling tracing
+    or raising — telemetry config must never break the host program.
+    """
+    raw = os.environ.get("PYTHINKER_OTEL_TRACE_SAMPLE_RATE", "").strip()
+    if not raw:
+        return DEFAULT_OTEL_TRACE_SAMPLE_RATE
+    try:
+        rate = float(raw)
+    except ValueError:
+        return DEFAULT_OTEL_TRACE_SAMPLE_RATE
+    if rate < 0.0:
+        return 0.0
+    if rate > 1.0:
+        return 1.0
+    return rate

pythinker_code/telemetry/crash.py

@@ -0,0 +1,191 @@
+"""Crash telemetry: capture uncaught exceptions via sys.excepthook and
+asyncio's exception handler, emit a ``crash`` event for in-process counting,
+forward the full exception to Sentry/Bugsink for debugging, then delegate to
+the original handler so the traceback still gets printed.
+
+Privacy posture:
+  - The OTel ``crash`` event still carries only the exception *class name*,
+    phase, and source — same as before.
+  - The Sentry capture path includes the stack trace (path-scrubbed by the
+    sentry module's ``before_send`` hook).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from types import TracebackType
+from typing import Any
+
+from pythinker_code.utils.logging import logger
+
+# ---------------------------------------------------------------------------
+# Phase tracking
+# ---------------------------------------------------------------------------
+
+_phase: str = "startup"
+"""Coarse lifecycle bucket recorded on each crash event.
+
+Valid values: ``startup`` (before app init finishes), ``runtime``
+(normal operation), ``shutdown`` (after the main entry point returns).
+"""
+
+
+def set_phase(phase: str) -> None:
+    """Update the current lifecycle phase. Called by app entry points."""
+    global _phase
+    _phase = phase
+
+
+# ---------------------------------------------------------------------------
+# Filters
+# ---------------------------------------------------------------------------
+
+
+def _should_ignore_for_excepthook(exc_type: type[BaseException]) -> bool:
+    """Return True for exceptions that are not programming bugs.
+
+    - KeyboardInterrupt: Ctrl+C, already covered by the ``cancel`` event.
+    - SystemExit: deliberate exit, not a crash.
+    - click.ClickException (UsageError / BadParameter / ...): user-facing
+      CLI input errors, not program bugs.
+    """
+    if issubclass(exc_type, (KeyboardInterrupt, SystemExit)):
+        return True
+    try:
+        import click
+
+        if issubclass(exc_type, click.exceptions.ClickException):
+            return True
+    except ImportError:
+        pass
+    return False
+
+
+def _should_ignore_for_asyncio(exc: BaseException) -> bool:
+    """Return True for normal async control-flow exceptions.
+
+    ``asyncio.QueueShutDown`` is raised by Python's queue API when a wire stream
+    is intentionally closed. UI consumers catch it, but vendor asyncio
+    integrations can still observe the task boundary, so treat it like
+    cancellation rather than a crash.
+    """
+    if isinstance(exc, asyncio.CancelledError):
+        return True
+    queue_shutdown = getattr(asyncio, "QueueShutDown", None)
+    return queue_shutdown is not None and isinstance(exc, queue_shutdown)
+
+
+def _should_suppress_asyncio_context(context: dict[str, Any]) -> bool:
+    """Return True for asyncio-handler contexts that should stay invisible.
+
+    Prompt-toolkit displays asyncio default-handler output in an overlay. During
+    Esc/interrupt cleanup, some cancelled/GC'd tasks can call the loop exception
+    handler with no ``exception`` field at all, which renders as
+    ``Unhandled exception in event loop: Exception None`` and steals focus until
+    ENTER is pressed. With no exception object there is nothing actionable to
+    report, so suppress the default handler for that known-noisy context.
+    """
+    exc = context.get("exception")
+    if exc is None:
+        return True
+    return isinstance(exc, BaseException) and _should_ignore_for_asyncio(exc)
+
+
+# ---------------------------------------------------------------------------
+# sys.excepthook
+# ---------------------------------------------------------------------------
+
+_original_excepthook: Any = None
+
+
+def _excepthook(
+    exc_type: type[BaseException],
+    exc: BaseException,
+    tb: TracebackType | None,
+) -> None:
+    if not _should_ignore_for_excepthook(exc_type):
+        # Any failure inside telemetry must not mask the underlying crash.
+        try:
+            from pythinker_code.telemetry import sentry as _sentry
+            from pythinker_code.telemetry import track
+
+            track(
+                "crash",
+                error_type=exc_type.__name__,
+                where=_phase,
+                source="excepthook",
+            )
+            _sentry.capture_exception(exc)
+        except Exception:
+            logger.debug("Telemetry crash capture failed", exc_info=True)
+
+    # Always delegate so the traceback is still printed.
+    handler = _original_excepthook if _original_excepthook is not None else sys.__excepthook__
+    handler(exc_type, exc, tb)
+
+
+def install_crash_handlers() -> None:
+    """Install the process-level ``sys.excepthook``.
+
+    Idempotent: repeated calls are no-ops. Should be called as early as
+    possible in the entry point so startup-phase exceptions are captured.
+    """
+    global _original_excepthook
+    if sys.excepthook is _excepthook:
+        return
+    _original_excepthook = sys.excepthook
+    sys.excepthook = _excepthook
+
+
+# ---------------------------------------------------------------------------
+# asyncio exception handler
+# ---------------------------------------------------------------------------
+
+_original_asyncio_handler: Any = None
+
+
+def _asyncio_handler(
+    loop: asyncio.AbstractEventLoop,
+    context: dict[str, Any],
+) -> None:
+    if _should_suppress_asyncio_context(context):
+        return
+
+    exc = context.get("exception")
+    if exc is not None:
+        try:
+            from pythinker_code.telemetry import sentry as _sentry
+            from pythinker_code.telemetry import track
+
+            track(
+                "crash",
+                error_type=type(exc).__name__,
+                where=_phase,
+                source="asyncio_task",
+            )
+            _sentry.capture_exception(exc)
+        except Exception:
+            logger.debug("Telemetry crash capture failed", exc_info=True)
+
+    # Delegate so the original logging behavior (or custom handler) runs.
+    if _original_asyncio_handler is not None:
+        _original_asyncio_handler(loop, context)
+    else:
+        loop.default_exception_handler(context)
+
+
+def install_asyncio_handler(loop: asyncio.AbstractEventLoop | None = None) -> None:
+    """Install the crash handler on the given (or current running) loop.
+
+    Idempotent on the same loop. If a custom handler was already installed,
+    it is preserved and still invoked after the crash event is recorded.
+    """
+    global _original_asyncio_handler
+    if loop is None:
+        loop = asyncio.get_running_loop()
+    current = loop.get_exception_handler()
+    if current is _asyncio_handler:
+        return
+    _original_asyncio_handler = current
+    loop.set_exception_handler(_asyncio_handler)

pythinker_code/telemetry/errors.py

@@ -0,0 +1,113 @@
+"""Helper for reporting handled exceptions to Sentry/Bugsink + OTel.
+
+Use this at any except-block site that intentionally turns an exception into
+a graceful user-facing error result (a ``ToolError``, a TUI message, a logged
+warning). The site keeps its existing failure-rendering behaviour; the helper
+additionally informs the monitoring stack so dashboards can see the failure
+rate, class, and bucket.
+
+Privacy posture
+---------------
+Only pass primitive enum-like attributes through ``**attrs`` (tool name,
+class names, mode flags). The OTel ``error`` event is forwarded verbatim, so
+**never** pass user input, file paths, or code snippets there. Sentry is fine
+with full exception data — its ``before_send`` hook already scrubs paths and
+strips PII before transmission.
+
+Both forwarding paths are wrapped in :func:`contextlib.suppress` because
+telemetry must never break the host program.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+import time
+from collections import deque
+from dataclasses import dataclass
+from typing import Any
+
+from pythinker_code.telemetry import sentry as _sentry
+from pythinker_code.telemetry import track
+
+# ---------------------------------------------------------------------------
+# Process-local ring buffer of recent errors
+# ---------------------------------------------------------------------------
+# Keeps just enough metadata to populate the ``/report-error`` slash command
+# without retaining the full exception object (which can hold large frames
+# and references). Class name + a short, redacted message is what shows in
+# the buffer; the *full* scrubbed stack is already in Sentry/Bugsink.
+
+_RECENT_BUFFER_SIZE = 10
+_ABSOLUTE_PATH_RE = re.compile(r"(?<!\w)(?:/[\w .~+@%=-]+)+|[A-Za-z]:\\(?:[^\\\r\n]+\\?)+")
+
+
+def _redact_recent_message(message: str) -> str:
+    return _ABSOLUTE_PATH_RE.sub("<path>", message)[:200]
+
+
+@dataclass(frozen=True, slots=True)
+class RecentError:
+    timestamp: float
+    site: str
+    exc_class: str
+    message: str  # truncated to 200 chars
+    tool: str | None
+
+
+_recent: deque[RecentError] = deque(maxlen=_RECENT_BUFFER_SIZE)
+
+
+def recent_errors() -> list[RecentError]:
+    """Snapshot of the most-recent reported errors (oldest first)."""
+    return list(_recent)
+
+
+def clear_recent_errors() -> None:
+    """Drop the recent-errors buffer. Used by tests and by ``/report-error``
+    after a successful submission."""
+    _recent.clear()
+
+
+def report_handled_error(
+    exc: BaseException,
+    *,
+    site: str,
+    tool: str | None = None,
+    **attrs: bool | int | float | str | None,
+) -> None:
+    """Forward a caught-and-rendered exception to Sentry + the OTel error stream.
+
+    Args:
+        exc: The exception that was caught at the call site.
+        site: Stable identifier for the catch site, e.g. ``"tool.read"`` or
+            ``"auth.oauth.refresh"``. Used to bucket failures in dashboards.
+            Must be a stable enum-like string, not a free-form message.
+        tool: Optional tool name when the site is a tool implementation
+            (e.g. ``"ReadFile"``). Forwarded as a separate property so SigNoz
+            queries can group by tool without parsing ``site``.
+        **attrs: Additional primitive enum-like attributes. Booleans, numbers
+            and short strings only. Values must not contain user input,
+            absolute paths, or code snippets.
+    """
+    properties: dict[str, Any] = {
+        "site": site,
+        "exc_class": type(exc).__name__,
+    }
+    if tool is not None:
+        properties["tool"] = tool
+    properties.update(attrs)
+    with contextlib.suppress(Exception):
+        track("error", **properties)
+    with contextlib.suppress(Exception):
+        _sentry.capture_exception(exc)
+    with contextlib.suppress(Exception):
+        _recent.append(
+            RecentError(
+                timestamp=time.time(),
+                site=site,
+                exc_class=type(exc).__name__,
+                message=_redact_recent_message(str(exc)),
+                tool=tool,
+            )
+        )