pythinker-code 2.0.0__py3-none-any.whl

pythinker_code/telemetry/__init__.py

@@ -0,0 +1,211 @@
+"""
+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."""
+_session_started_sessions: set[str] = set()
+"""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)
+    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,54 @@
+"""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. Disable
+telemetry entirely with ``PYTHINKER_DISABLE_TELEMETRY=1``.
+"""
+
+from __future__ import annotations
+
+import os
+
+# ---------------------------------------------------------------------------
+# 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)
+
+
+def is_disabled() -> bool:
+    """Master kill switch. ``PYTHINKER_DISABLE_TELEMETRY=1`` (or ``true``) disables both
+    Sentry and OTel emission for the process."""
+    raw = os.environ.get("PYTHINKER_DISABLE_TELEMETRY", "").strip().lower()
+    return raw in {"1", "true", "yes", "on"}

pythinker_code/telemetry/crash.py

@@ -0,0 +1,157 @@
+"""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
+
+# ---------------------------------------------------------------------------
+# 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
+
+
+# ---------------------------------------------------------------------------
+# 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:
+            pass
+
+    # 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:
+    exc = context.get("exception")
+    # CancelledError during shutdown/cancellation is normal control flow.
+    if exc is not None and not isinstance(exc, asyncio.CancelledError):
+        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:
+            pass
+
+    # 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/metrics.py

@@ -0,0 +1,208 @@
+"""Pre-bound OTel metric instruments for the agent loop.
+
+Call sites stay declarative — they import the instruments and call ``.add()``
+or ``.record()``. When telemetry is disabled, the instruments are still
+present but back onto the no-op meter, so the cost is one attribute lookup
+plus a no-op call.
+
+Initialization happens automatically: ``otel.init()`` calls ``bind()`` once
+the SDK MeterProvider is up. Until then, everything points at the global
+no-op meter so unit tests and pre-init code paths stay safe.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from opentelemetry import metrics as _metrics
+from opentelemetry.metrics import Counter, Histogram, Meter
+
+# ---------------------------------------------------------------------------
+# Module-level instrument handles
+# ---------------------------------------------------------------------------
+# Initialized lazily on first ``bind()``. Until then, the global no-op meter
+# returns no-op instruments — accessing them is safe.
+
+_meter: Meter = _metrics.get_meter("pythinker-code")
+
+# --- Turn-level ---
+turn_total: Counter = _meter.create_counter(
+    "pythinker.turn.total",
+    description="Number of agent turns completed (one user message → final response).",
+    unit="1",
+)
+turn_duration_seconds: Histogram = _meter.create_histogram(
+    "pythinker.turn.duration_seconds",
+    description="End-to-end agent-turn duration.",
+    unit="s",
+)
+turn_step_count: Histogram = _meter.create_histogram(
+    "pythinker.turn.step_count",
+    description="Number of inner steps (LLM calls + tool loops) per turn.",
+    unit="1",
+)
+
+# --- LLM-level ---
+llm_calls_total: Counter = _meter.create_counter(
+    "pythinker.llm.calls_total",
+    description="Number of LLM API calls.",
+    unit="1",
+)
+llm_duration_seconds: Histogram = _meter.create_histogram(
+    "pythinker.llm.duration_seconds",
+    description="LLM request duration.",
+    unit="s",
+)
+llm_input_tokens: Counter = _meter.create_counter(
+    "pythinker.llm.input_tokens",
+    description="Input/prompt tokens consumed (diagnostic — pythinker is BYO-key).",
+    unit="1",
+)
+llm_output_tokens: Counter = _meter.create_counter(
+    "pythinker.llm.output_tokens",
+    description="Output/completion tokens generated (diagnostic).",
+    unit="1",
+)
+
+# --- Tool-level ---
+tool_calls_total: Counter = _meter.create_counter(
+    "pythinker.tool.calls_total",
+    description="Number of tool invocations (Read, Bash, Edit, MCP, …).",
+    unit="1",
+)
+tool_duration_seconds: Histogram = _meter.create_histogram(
+    "pythinker.tool.duration_seconds",
+    description="Tool execution duration.",
+    unit="s",
+)
+
+# --- Errors ---
+errors_total: Counter = _meter.create_counter(
+    "pythinker.errors_total",
+    description="Errors observed by kind (api_error, tool_error, crash, …).",
+    unit="1",
+)
+
+
+def bind(meter: Meter) -> None:
+    """Re-bind every instrument to a real (SDK) meter once OTel is initialized.
+
+    Called once from ``otel.init`` after the MeterProvider is up. Subsequent
+    calls are idempotent — but we replace the module-level handles so existing
+    references stay correct (Python rebinds names, not objects).
+    """
+    global _meter
+    global turn_total, turn_duration_seconds, turn_step_count
+    global llm_calls_total, llm_duration_seconds, llm_input_tokens, llm_output_tokens
+    global tool_calls_total, tool_duration_seconds, errors_total
+
+    _meter = meter
+    turn_total = meter.create_counter(
+        "pythinker.turn.total",
+        description="Number of agent turns completed (one user message → final response).",
+        unit="1",
+    )
+    turn_duration_seconds = meter.create_histogram(
+        "pythinker.turn.duration_seconds",
+        description="End-to-end agent-turn duration.",
+        unit="s",
+    )
+    turn_step_count = meter.create_histogram(
+        "pythinker.turn.step_count",
+        description="Number of inner steps (LLM calls + tool loops) per turn.",
+        unit="1",
+    )
+    llm_calls_total = meter.create_counter(
+        "pythinker.llm.calls_total",
+        description="Number of LLM API calls.",
+        unit="1",
+    )
+    llm_duration_seconds = meter.create_histogram(
+        "pythinker.llm.duration_seconds",
+        description="LLM request duration.",
+        unit="s",
+    )
+    llm_input_tokens = meter.create_counter(
+        "pythinker.llm.input_tokens",
+        description="Input/prompt tokens consumed (diagnostic — pythinker is BYO-key).",
+        unit="1",
+    )
+    llm_output_tokens = meter.create_counter(
+        "pythinker.llm.output_tokens",
+        description="Output/completion tokens generated (diagnostic).",
+        unit="1",
+    )
+    tool_calls_total = meter.create_counter(
+        "pythinker.tool.calls_total",
+        description="Number of tool invocations (Read, Bash, Edit, MCP, …).",
+        unit="1",
+    )
+    tool_duration_seconds = meter.create_histogram(
+        "pythinker.tool.duration_seconds",
+        description="Tool execution duration.",
+        unit="s",
+    )
+    errors_total = meter.create_counter(
+        "pythinker.errors_total",
+        description="Errors observed by kind (api_error, tool_error, crash, …).",
+        unit="1",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Recording helpers — used by the agent loop
+# ---------------------------------------------------------------------------
+
+
+def record_turn(*, duration_seconds: float, step_count: int, stop_reason: str) -> None:
+    """Record a completed agent turn."""
+    attrs: dict[str, Any] = {"stop_reason": stop_reason}
+    turn_total.add(1, attrs)
+    turn_duration_seconds.record(duration_seconds, attrs)
+    turn_step_count.record(step_count, attrs)
+
+
+def record_llm_call(
+    *,
+    duration_seconds: float,
+    system: str,
+    model: str,
+    input_tokens: int | None = None,
+    output_tokens: int | None = None,
+    success: bool = True,
+) -> None:
+    """Record one LLM API call."""
+    attrs: dict[str, Any] = {
+        "gen_ai.system": system,
+        "gen_ai.request.model": model,
+        "success": success,
+    }
+    llm_calls_total.add(1, attrs)
+    llm_duration_seconds.record(duration_seconds, attrs)
+    if input_tokens is not None and input_tokens > 0:
+        llm_input_tokens.add(input_tokens, attrs)
+    if output_tokens is not None and output_tokens > 0:
+        llm_output_tokens.add(output_tokens, attrs)
+
+
+def record_tool_call(
+    *,
+    tool_name: str,
+    duration_seconds: float,
+    success: bool,
+    error_type: str | None = None,
+) -> None:
+    """Record one tool invocation."""
+    attrs: dict[str, Any] = {"tool.name": tool_name, "success": success}
+    if error_type:
+        attrs["error_type"] = error_type
+    tool_calls_total.add(1, attrs)
+    tool_duration_seconds.record(duration_seconds, attrs)
+
+
+def record_error(*, kind: str, error_type: str | None = None) -> None:
+    """Record an error by kind (api_error, tool_error, crash, …)."""
+    attrs: dict[str, Any] = {"kind": kind}
+    if error_type:
+        attrs["error_type"] = error_type
+    errors_total.add(1, attrs)