feat: add daemon telemetry foundation

python/ktx-daemon/pyproject.toml

@@ -12,6 +12,7 @@ dependencies = [
     "numpy>=2.2.6",
     "orjson>=3.11.4",
     "pandas>=2.2.3",
+    "posthog>=7.0.0",
     "psycopg[binary]>=3.2.0",
     "pydantic>=2.9.0",
     "requests>=2.32.0",

python/ktx-daemon/src/ktx_daemon/telemetry/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from ktx_daemon.telemetry.emitter import error_class, track_telemetry_event
+
+__all__ = ["error_class", "track_telemetry_event"]

python/ktx-daemon/src/ktx_daemon/telemetry/emitter.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+from collections.abc import Mapping
+
+from ktx_daemon.telemetry.events import build_telemetry_event
+from ktx_daemon.telemetry.identity import load_telemetry_identity
+
+POSTHOG_PROJECT_API_KEY = ""
+POSTHOG_HOST = ""
+
+
+def _host(env: Mapping[str, str]) -> str:
+    return env.get("KTX_TELEMETRY_ENDPOINT") or POSTHOG_HOST
+
+
+def _live_configured(host: str) -> bool:
+    return bool(POSTHOG_PROJECT_API_KEY.strip() and host.strip())
+
+
+def _debug_enabled(env: Mapping[str, str]) -> bool:
+    return env.get("KTX_TELEMETRY_DEBUG") == "1"
+
+
+def _scrub_error_class(error: BaseException) -> str | None:
+    name = type(error).__name__
+    if len(name) > 80:
+        return None
+    if any(marker in name for marker in ("/", "\\", "@", "://")):
+        return None
+    if not name[:1].isupper() or not name.replace("_", "").isalnum():
+        return None
+    return name
+
+
+def error_class(error: BaseException) -> str | None:
+    return _scrub_error_class(error)
+
+
+def track_telemetry_event(
+    name: str,
+    fields: dict[str, Any],
+    *,
+    project_id: str | None = None,
+    home_dir: Path | None = None,
+    env: Mapping[str, str] | None = None,
+) -> None:
+    source_env = env or os.environ
+    identity = load_telemetry_identity(home_dir=home_dir, env=source_env)
+    if not identity.enabled or not identity.install_id:
+        return
+
+    try:
+        event = build_telemetry_event(name, fields)
+    except ValueError:
+        return
+
+    groups = {"project": project_id} if project_id else None
+
+    if _debug_enabled(source_env):
+        sys.stderr.write(
+            "[telemetry] "
+            + json.dumps(
+                {
+                    "distinctId": identity.install_id,
+                    "event": event["event"],
+                    "properties": event["properties"],
+                    "groups": groups,
+                },
+                sort_keys=True,
+            )
+            + "\n"
+        )
+        return
+
+    host = _host(source_env)
+    if not _live_configured(host):
+        return
+
+    try:
+        from posthog import Posthog
+
+        client = Posthog(
+            POSTHOG_PROJECT_API_KEY,
+            host=host,
+            flush_at=1,
+            flush_interval=0,
+            sync_mode=True,
+            timeout=1,
+            disable_geoip=True,
+        )
+        client.capture(
+            event=event["event"],
+            distinct_id=identity.install_id,
+            properties=event["properties"],
+            groups=groups,
+            disable_geoip=True,
+        )
+        client.shutdown()
+    except Exception:
+        return

python/ktx-daemon/src/ktx_daemon/telemetry/events.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+import os
+import platform
+import sys
+from pathlib import Path
+from typing import Any
+
+from ktx_daemon import VERSION
+
+SCHEMA_PATH = Path(__file__).with_name("events.schema.json")
+COMMON_FIELDS = {
+    "cliVersion",
+    "nodeVersion",
+    "osPlatform",
+    "osRelease",
+    "arch",
+    "runtime",
+    "isCi",
+}
+DAEMON_EVENTS = {
+    "daemon_started",
+    "daemon_stopped",
+    "sl_plan_completed",
+    "sql_gen_completed",
+}
+
+
+def _schema_catalog() -> dict[str, set[str]]:
+    raw = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+    return {
+        event["name"]: set(event["fields"])
+        for event in raw["x-ktx-catalog"]
+        if event["name"] in DAEMON_EVENTS
+    }
+
+
+EVENT_FIELDS = _schema_catalog()
+
+
+def _common_envelope() -> dict[str, Any]:
+    return {
+        "cliVersion": os.environ.get("KTX_DAEMON_VERSION", VERSION),
+        "nodeVersion": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+        "osPlatform": sys.platform,
+        "osRelease": platform.release(),
+        "arch": platform.machine(),
+        "runtime": "daemon-py",
+        "isCi": bool(os.environ.get("CI")),
+    }
+
+
+def build_telemetry_event(name: str, fields: dict[str, Any]) -> dict[str, Any]:
+    allowed = EVENT_FIELDS.get(name)
+    if allowed is None:
+        raise ValueError(f"unknown telemetry event: {name}")
+
+    extra = set(fields) - allowed
+    if extra:
+        raise ValueError(f"unknown telemetry fields for {name}: {sorted(extra)}")
+
+    missing = {
+        field for field in allowed if field not in fields and field != "errorClass"
+    }
+    if missing:
+        raise ValueError(f"missing telemetry fields for {name}: {sorted(missing)}")
+
+    return {
+        "event": name,
+        "properties": {**_common_envelope(), **fields},
+    }

python/ktx-daemon/src/ktx_daemon/telemetry/identity.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from collections.abc import Mapping
+
+IDENTITY_TTL_SECONDS = 60.0
+
+
+@dataclass(frozen=True)
+class TelemetryIdentity:
+    install_id: str | None
+    enabled: bool
+    path: Path
+
+
+_cache: tuple[float, Path, TelemetryIdentity] | None = None
+
+
+def _telemetry_path(home_dir: Path | None = None) -> Path:
+    return (home_dir or Path.home()) / ".ktx" / "telemetry.json"
+
+
+def _env_disables(env: Mapping[str, str] | None = None) -> bool:
+    source = env or os.environ
+    return bool(source.get("KTX_TELEMETRY_DISABLED") or source.get("DO_NOT_TRACK"))
+
+
+def _read_identity(path: Path) -> TelemetryIdentity:
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return TelemetryIdentity(install_id=None, enabled=False, path=path)
+
+    install_id = raw.get("installId")
+    enabled = raw.get("enabled")
+    if not isinstance(install_id, str) or enabled is not True:
+        return TelemetryIdentity(
+            install_id=install_id if isinstance(install_id, str) else None,
+            enabled=False,
+            path=path,
+        )
+
+    return TelemetryIdentity(install_id=install_id, enabled=True, path=path)
+
+
+def load_telemetry_identity(
+    *,
+    home_dir: Path | None = None,
+    env: Mapping[str, str] | None = None,
+    now: Callable[[], float] | None = None,
+) -> TelemetryIdentity:
+    global _cache
+
+    path = _telemetry_path(home_dir)
+    clock = now or time.monotonic
+    current = float(clock())
+
+    if _cache and _cache[1] == path and current - _cache[0] < IDENTITY_TTL_SECONDS:
+        cached = _cache[2]
+    else:
+        cached = _read_identity(path)
+        _cache = (current, path, cached)
+
+    if _env_disables(env):
+        return TelemetryIdentity(install_id=cached.install_id, enabled=False, path=path)
+
+    return cached
+
+
+def reset_identity_cache() -> None:
+    global _cache
+    _cache = None

python/ktx-daemon/tests/test_telemetry.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+from ktx_daemon.telemetry.emitter import track_telemetry_event
+from ktx_daemon.telemetry.events import build_telemetry_event
+from ktx_daemon.telemetry.identity import load_telemetry_identity, reset_identity_cache
+
+
+def write_identity(home: Path, *, enabled: bool = True) -> None:
+    target = home / ".ktx" / "telemetry.json"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        json.dumps(
+            {
+                "installId": "00000000-0000-4000-8000-000000000000",
+                "enabled": enabled,
+                "noticeShownAt": "2026-05-22T14:33:02.000Z",
+                "noticeShownVersion": 1,
+                "createdAt": "2026-05-22T14:33:02.000Z",
+            }
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+
+
+def test_identity_reads_file_with_ttl_cache(tmp_path: Path) -> None:
+    reset_identity_cache()
+    write_identity(tmp_path)
+
+    first = load_telemetry_identity(home_dir=tmp_path, now=lambda: 100.0)
+    assert first.enabled is True
+    assert first.install_id == "00000000-0000-4000-8000-000000000000"
+
+    write_identity(tmp_path, enabled=False)
+    cached = load_telemetry_identity(home_dir=tmp_path, now=lambda: 120.0)
+    assert cached.enabled is True
+
+    refreshed = load_telemetry_identity(home_dir=tmp_path, now=lambda: 161.0)
+    assert refreshed.enabled is False
+
+
+def test_identity_honors_python_env_kill_switches(tmp_path: Path) -> None:
+    reset_identity_cache()
+    write_identity(tmp_path)
+
+    disabled = load_telemetry_identity(
+        home_dir=tmp_path,
+        env={"KTX_TELEMETRY_DISABLED": "1"},
+        now=lambda: time.monotonic(),
+    )
+
+    assert disabled.enabled is False
+    assert disabled.install_id == "00000000-0000-4000-8000-000000000000"
+
+
+def test_event_builder_rejects_unknown_fields() -> None:
+    event = build_telemetry_event(
+        "sql_gen_completed",
+        {
+            "outcome": "ok",
+            "dialect": "postgres",
+            "durationMs": 5,
+        },
+    )
+
+    assert event["event"] == "sql_gen_completed"
+    assert event["properties"]["runtime"] == "daemon-py"
+
+    try:
+        build_telemetry_event(
+            "sql_gen_completed",
+            {
+                "outcome": "ok",
+                "dialect": "postgres",
+                "durationMs": 5,
+                "sql": "select * from private_table",
+            },
+        )
+    except ValueError as error:
+        assert "unknown telemetry fields" in str(error)
+    else:
+        raise AssertionError("expected unknown field rejection")
+
+
+def test_debug_emitter_writes_payload_without_network(tmp_path: Path, capsys) -> None:
+    reset_identity_cache()
+    write_identity(tmp_path)
+
+    track_telemetry_event(
+        "sl_plan_completed",
+        {
+            "outcome": "ok",
+            "stage": "transpile",
+            "durationMs": 12,
+            "sourceCount": 1,
+            "joinCount": 0,
+        },
+        project_id="a" * 64,
+        home_dir=tmp_path,
+        env={"KTX_TELEMETRY_DEBUG": "1"},
+    )
+
+    captured = capsys.readouterr()
+    assert '"event": "sl_plan_completed"' in captured.err
+    assert (
+        '"groups": {"project": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}'
+        in captured.err
+    )
+    assert "private_table" not in captured.err