deepctl-telemetry 0.0.7__tar.gz → 0.0.8__tar.gz

{deepctl_telemetry-0.0.7 → deepctl_telemetry-0.0.8}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: deepctl-telemetry
-Version: 0.0.7
-Summary: Opt-out phone-home telemetry for deepctl
+Version: 0.0.8
+Summary: Error reporting for deepctl; this version sends no telemetry
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>
 License-Expression: MIT
@@ -14,8 +14,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: deepctl-core>=0.1.10
-Requires-Dist: sentry-sdk>=2.0.0
+Requires-Dist: deepctl-core>=0.3.0
+Requires-Dist: sentry-sdk<3,>=2.35.0
 Requires-Dist: click>=8.0.0
 Requires-Dist: rich>=13.0.0
 
@@ -23,7 +23,7 @@ Requires-Dist: rich>=13.0.0
 
 > Part of [deepctl](https://github.com/deepgram/cli) — Official Deepgram CLI
 
-Opt-out phone-home telemetry for deepctl
+Error reporting for deepctl; this version sends no telemetry
 
 This package provides internal APIs for deepctl and its command packages. It is not intended for direct use.
 
@@ -50,7 +50,7 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `sentry-sdk>=2.0.0`
+- `sentry-sdk>=2.35.0,<3`
 - `click>=8.0.0`
 - `rich>=13.0.0`
 

{deepctl_telemetry-0.0.7 → deepctl_telemetry-0.0.8}/README.md

@@ -2,7 +2,7 @@
 
 > Part of [deepctl](https://github.com/deepgram/cli) — Official Deepgram CLI
 
-Opt-out phone-home telemetry for deepctl
+Error reporting for deepctl; this version sends no telemetry
 
 This package provides internal APIs for deepctl and its command packages. It is not intended for direct use.
 
@@ -29,7 +29,7 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `sentry-sdk>=2.0.0`
+- `sentry-sdk>=2.35.0,<3`
 - `click>=8.0.0`
 - `rich>=13.0.0`
 

{deepctl_telemetry-0.0.7 → deepctl_telemetry-0.0.8}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-telemetry"
-version = "0.0.7" # x-release-please-version
-description = "Opt-out phone-home telemetry for deepctl"
+version = "0.0.8" # x-release-please-version
+description = "Error reporting for deepctl; this version sends no telemetry"
 readme = "README.md"
 license = "MIT"
 authors = [{ name = "Deepgram", email = "devrel@deepgram.com" }]
@@ -21,8 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "telemetry", "sentry"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
-    "sentry-sdk>=2.0.0",
+    "deepctl-core>=0.3.0",
+    "sentry-sdk>=2.35.0,<3",
     "click>=8.0.0",
     "rich>=13.0.0",
 ]

deepctl_telemetry-0.0.8/src/deepctl_telemetry/__init__.py

@@ -0,0 +1,15 @@
+"""Error reporting for deepctl. This version sends no telemetry."""
+
+from .client import disable_for_run, init_telemetry, is_enabled, report_exception
+from .notice import install_help_notice, render_notice
+
+__all__ = [
+    "disable_for_run",
+    "init_telemetry",
+    "install_help_notice",
+    "is_enabled",
+    "render_notice",
+    "report_exception",
+]
+
+__version__ = "0.0.8"  # x-release-please-version

deepctl_telemetry-0.0.8/src/deepctl_telemetry/client.py

@@ -0,0 +1,607 @@
+"""Sentry-backed telemetry client: unexpected errors only, allowlisted fields.
+
+This version has no built-in destination, so it sends no telemetry. A
+report can go only to a DEEPCTL_TELEMETRY_DSN override on a loopback
+address, which exists for tests and local sinks. Without one, telemetry is
+off: no hooks are installed and the SDK is never imported.
+
+The SDK is never imported on the success path. ``init_telemetry`` only
+records the enabled decision and installs stdlib exception hooks;
+``report_exception`` imports and initializes the SDK when an error actually
+reaches it, sends one event, and flushes within a fixed time budget.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import re
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from deepctl_core import Config
+    from sentry_sdk.types import Event, Hint
+
+
+# Build switch. Set to False to ship a build in which telemetry is inert:
+# no hooks are installed, the SDK is never imported, DEEPCTL_TELEMETRY_DSN is
+# ignored, and `--help` says this version of dg sends no telemetry.
+TELEMETRY_BUILD_ENABLED = True
+
+# There is no built-in destination: _dsn() returns a DEEPCTL_TELEMETRY_DSN
+# override on a loopback address, or None, and with None nothing is sent.
+
+DSN_ENV_VAR = "DEEPCTL_TELEMETRY_DSN"
+DISABLE_ENV_VAR = "DEEPCTL_TELEMETRY_DISABLED"
+
+# Values of DEEPCTL_TELEMETRY_DISABLED that leave telemetry on. Any other
+# non-empty value turns it off.
+_ENV_KEEPS_ON = frozenset({"0", "false", "no", "off"})
+
+# Flush timeout once the SDK is initialized, and the cap on the whole report
+# (SDK import and init included). The flush always gets at least the floor.
+FLUSH_TIMEOUT_SECONDS = 0.5
+REPORT_BUDGET_SECONDS = 0.6
+FLUSH_FLOOR_SECONDS = 0.05
+
+
+def _fresh_state() -> dict[str, Any]:
+    """Per-run state, stdlib types only.
+
+    `opt_out` names the switch that turned telemetry off ("build", "dsn"
+    when there is no destination, "flag", "env" or "config"); `config_path`
+    is the user config file the decision was read from; `reported` is set
+    once a report starts, `sent` once an event has been handed to the
+    transport.
+    """
+    return {
+        "enabled": False,
+        "opt_out": None,
+        "config_path": None,
+        "hooks_installed": False,
+        "reported": False,
+        "sent": False,
+        "disabled_for_run": False,
+    }
+
+
+_state: dict[str, Any] = _fresh_state()
+_report_lock = threading.Lock()
+
+
+def disable_for_run() -> None:
+    """Turn telemetry off for this process only (`dg --no-telemetry`)."""
+    _state["disabled_for_run"] = True
+    _state["enabled"] = False
+
+
+def _env_opts_out() -> bool:
+    value = os.environ.get(DISABLE_ENV_VAR, "").strip().lower()
+    return bool(value) and value not in _ENV_KEEPS_ON
+
+
+# Keys whose repetition in a config file makes the telemetry setting
+# ambiguous; a file that repeats one counts as opted out.
+_TELEMETRY_KEYS = frozenset({"telemetry", "enabled", "telemetry.enabled"})
+
+
+def _default_config_path() -> Path:
+    """The default user config file (the one Config uses without --config)."""
+    import platformdirs
+
+    return Path(platformdirs.user_config_dir("deepctl", "deepgram")) / "config.yaml"
+
+
+_REFUSED = object()
+
+
+def _file_opts_out(config_file: Path, text: object = None) -> bool:
+    """Whether one user config file turns telemetry off.
+
+    `text` is the file's content as Config read it, or _REFUSED when Config
+    didn't use the file. Without it, the file is read here through core's
+    config reader (read_user_config_text), with the same limits and
+    refusals as a config load, and never at all when Config refused it.
+    Telemetry never parses config YAML itself: core's load_config_text
+    does, with every load limit.
+
+    Telemetry stays on when the file is absent or empty, or has no
+    `telemetry` setting, or sets `enabled` to the boolean `true`. A file
+    that a load would refuse (not a regular file, too large, a bomb, a
+    parse error, an in-place rewrite that didn't finish, untrusted in an AI
+    agent session) turns it off, as does one that repeats a telemetry key,
+    has a `telemetry` section that isn't a mapping, or holds any other
+    `enabled` value. A top-level `telemetry.enabled` key counts too.
+    """
+    if text is _REFUSED:
+        return True
+    try:
+        from deepctl_core.config import load_config_text, read_user_config_text
+    except ImportError:  # an older deepctl-core: no capped reader to use
+        return True
+    if not isinstance(text, str):
+        try:
+            text = read_user_config_text(config_file)
+        except FileNotFoundError:
+            return False
+        except Exception:
+            return True
+        if text is None:
+            return True
+    try:
+        data, repeated = load_config_text(text, _TELEMETRY_KEYS)
+    except Exception:
+        return True
+    if repeated:
+        return True
+    if data is None:
+        return False
+    if not isinstance(data, dict):
+        return True
+    if "telemetry.enabled" in data and data["telemetry.enabled"] is not True:
+        return True
+    if "telemetry" not in data:
+        return False
+    section = data["telemetry"]
+    if not isinstance(section, dict):
+        return True
+    if "enabled" not in section:
+        return False
+    return section["enabled"] is not True
+
+
+def _user_config_opts_out(config: Config) -> bool:
+    """Read `telemetry.enabled` from the user's own config files only.
+
+    Both the default config file and, with `--config`, the named file count;
+    telemetry is off if either turns it off. The file Config loaded is
+    parsed from the text Config kept, and counts as opted out when Config
+    refused it. The merged Config is not used, because it also holds the
+    project's `deepgram.yaml`.
+    """
+    files: dict[str, object] = {}
+    explicit = getattr(config, "config_path", None)
+    if explicit is not None:
+        text = getattr(config, "user_config_text", None)
+        if getattr(config, "user_config_refused", False) is True:
+            files[str(explicit)] = _REFUSED
+        else:
+            files[str(explicit)] = text if isinstance(text, str) else None
+    try:
+        files.setdefault(str(_default_config_path()), None)
+    except Exception:
+        return True
+    return any(_file_opts_out(Path(path), text) for path, text in files.items())
+
+
+def _opt_out_source(config: Config) -> str | None:
+    if not TELEMETRY_BUILD_ENABLED:
+        return "build"
+    if _dsn() is None:
+        return "dsn"
+    if _state["disabled_for_run"]:
+        return "flag"
+    if _env_opts_out():
+        return "env"
+    if _user_config_opts_out(config):
+        return "config"
+    return None
+
+
+def is_enabled(config: Config) -> bool:
+    """Whether telemetry may report an error for this invocation.
+
+    Resolution order: the build switch, then whether there is a
+    destination (a loopback DEEPCTL_TELEMETRY_DSN; without one telemetry is
+    off), then `--no-telemetry` for this run, then the env override
+    (DEEPCTL_TELEMETRY_DISABLED), then `telemetry.enabled` in the user's
+    config file (default on). The project's `deepgram.yaml` is never read.
+    """
+    return _opt_out_source(config) is None
+
+
+def init_telemetry(config: Config) -> bool:
+    """Record whether telemetry is on and install the error hooks.
+
+    Called after option parsing with the resolved Config, so `--config` and
+    `--no-telemetry` are honored. Does not import the SDK. Safe to call
+    more than once; the latest call wins. Returns whether telemetry is on.
+    """
+    opt_out = _opt_out_source(config)
+    _state["opt_out"] = opt_out
+    _state["enabled"] = opt_out is None
+    path = getattr(config, "config_path", None)
+    _state["config_path"] = str(path) if path is not None else None
+    if _state["enabled"]:
+        _install_hooks()
+    return bool(_state["enabled"])
+
+
+def _install_hooks() -> None:
+    """Chain stdlib hooks for exceptions that escape `main()` or a thread."""
+    if _state["hooks_installed"]:
+        return
+    previous_excepthook = sys.excepthook
+    previous_thread_hook = threading.excepthook
+
+    def excepthook(
+        exc_type: type[BaseException],
+        exc: BaseException,
+        tb: TracebackType | None,
+    ) -> None:
+        report_exception(exc)
+        previous_excepthook(exc_type, exc, tb)
+
+    def thread_excepthook(args: threading.ExceptHookArgs) -> None:
+        if args.exc_value is not None:
+            report_exception(args.exc_value)
+        previous_thread_hook(args)
+
+    sys.excepthook = excepthook
+    threading.excepthook = thread_excepthook
+    _state["hooks_installed"] = True
+
+
+def _unexpected_error_types() -> tuple[type[BaseException], ...]:
+    try:
+        from deepctl_core.base_command import UnexpectedCommandError
+    except ImportError:
+        return ()
+    return (UnexpectedCommandError,)
+
+
+def _reportable(exc: BaseException | None) -> BaseException | None:
+    """The exception worth reporting, or None for user errors and exits.
+
+    Any ClickException is an expected outcome (a usage error, or a command
+    reporting a problem to the user), except deepctl-core's
+    UnexpectedCommandError: BaseCommand raises it `from` an error it didn't
+    expect, and that cause is what gets reported.
+    """
+    import click
+
+    if isinstance(exc, _unexpected_error_types()):
+        exc = exc.__cause__
+    if exc is None or isinstance(exc, click.ClickException):
+        return None
+    if isinstance(exc, (click.exceptions.Exit, click.Abort)):
+        return None
+    return exc if isinstance(exc, Exception) else None
+
+
+def _dsn() -> str | None:
+    """A DEEPCTL_TELEMETRY_DSN override on loopback, or None.
+
+    There is no built-in DSN, so without an override there is nowhere to
+    send a report. The override exists for tests and local sinks, so a
+    non-loopback value is ignored rather than allowed to redirect reports.
+    """
+    override = os.environ.get(DSN_ENV_VAR, "").strip()
+    if not override:
+        return None
+    try:
+        import ipaddress
+        from urllib.parse import urlsplit
+
+        host = urlsplit(override).hostname or ""
+        if host == "localhost" or ipaddress.ip_address(host).is_loopback:
+            return override
+    except ValueError:
+        pass
+    return None
+
+
+def report_exception(exc: BaseException | None) -> bool:
+    """Send one error report for `exc` if telemetry is on.
+
+    Does nothing, and never imports the SDK, without a loopback
+    DEEPCTL_TELEMETRY_DSN. Imports and initializes the SDK only here. At
+    most one report per process. The flush waits at most
+    FLUSH_TIMEOUT_SECONDS after init, and the whole call is held to
+    REPORT_BUDGET_SECONDS (but the flush always gets FLUSH_FLOOR_SECONDS).
+    Never raises an Exception; a KeyboardInterrupt during the flush
+    propagates to the caller. Returns whether an event was handed to the
+    SDK.
+    """
+    started = time.monotonic()
+    with _report_lock:
+        if not TELEMETRY_BUILD_ENABLED or not _state["enabled"] or _state["reported"]:
+            return False
+        dsn = _dsn()
+        if dsn is None:
+            return False
+        target = _reportable(exc)
+        if target is None:
+            return False
+        _state["reported"] = True
+
+    try:
+        import sentry_sdk
+
+        try:
+            cli_version = _read_cli_version()
+        except Exception:
+            cli_version = "unknown"
+
+        sentry_sdk.init(**_sdk_options(dsn, cli_version))
+        sentry_sdk.capture_exception(target)
+        left = REPORT_BUDGET_SECONDS - (time.monotonic() - started)
+        timeout = max(FLUSH_FLOOR_SECONDS, min(FLUSH_TIMEOUT_SECONDS, left))
+        sentry_sdk.flush(timeout=timeout)
+        return True
+    except Exception:
+        return False
+
+
+def _read_cli_version() -> str:
+    import importlib.metadata
+
+    return importlib.metadata.version("deepctl")
+
+
+def _sdk_options(dsn: str, cli_version: str) -> dict[str, Any]:
+    """Explicit SDK settings: one error event per failure and nothing else.
+
+    No integrations at all (no argv, modules, logging, breadcrumbs, and none
+    of the SDK's own excepthook or threading capture: the stdlib hooks in
+    `_install_hooks` are the only capture path, so the once-per-process
+    rule holds). No traces, profiles, sessions or logs, and no locals,
+    source lines, stack snapshots or hostname. No proxy: an empty
+    `http_proxy` and `https_proxy` stop the SDK from falling back to a proxy
+    from the environment or the system settings, so a report to a loopback
+    DSN stays on this machine. `before_send` and `before_send_transaction`
+    then rebuild whatever is left from the allowlist in `_rebuild_event`.
+    """
+    return {
+        "dsn": dsn,
+        "release": f"deepctl@{cli_version}",
+        "environment": "production",
+        "default_integrations": False,
+        "auto_enabling_integrations": False,
+        "integrations": [],
+        "traces_sample_rate": 0.0,
+        "profiles_sample_rate": 0.0,
+        "enable_logs": False,
+        "auto_session_tracking": False,
+        "attach_stacktrace": False,
+        "include_local_variables": False,
+        "include_source_context": False,
+        "max_breadcrumbs": 0,
+        "send_default_pii": False,
+        "send_client_reports": False,
+        "server_name": "",
+        "spotlight": False,
+        "http_proxy": "",
+        "https_proxy": "",
+        "before_send": _before_send,
+        "before_send_transaction": _rebuild_event,
+    }
+
+
+def _before_send(event: Event, hint: Hint) -> Event | None:
+    """Rebuild the event, and let only the first one in the process through."""
+    with _report_lock:
+        if _state["sent"]:
+            return None
+        rebuilt = _rebuild_event(event, hint)
+        if rebuilt is not None:
+            _state["sent"] = True
+        return rebuilt
+
+
+def _is_broken_pipe(event: Event) -> bool:
+    """Identify events caused by writing to a closed/broken output stream.
+
+    When `dg mcp` runs as an MCP server, the host can close stdio while the
+    CLI is still finishing up. Any residual write (an advisory notification, a
+    console error message) then raises ``BrokenPipeError`` — or rich's
+    ``ValueError: I/O operation on closed file`` when the underlying stream is
+    already closed. Neither is an actionable CLI bug, so drop them rather than
+    page the DX team.
+    """
+    for exc in (event.get("exception") or {}).get("values") or []:
+        exc_type = exc.get("type") or ""
+        if exc_type == "BrokenPipeError":
+            return True
+        if exc_type == "ValueError" and "closed file" in (exc.get("value") or ""):
+            return True
+    return False
+
+
+# Top-level packages whose module and exception-type names may be sent: dg's
+# own packages, the libraries it calls, and the standard library. Any other
+# module (a plugin, even one named deepctl_*, a user script, `__main__`) is
+# sent as OTHER_NAME. Keep _FIRST_PARTY in step with packages/*/src.
+_FIRST_PARTY = frozenset(
+    {
+        "deepctl",
+        "deepctl_cmd_api",
+        "deepctl_cmd_billing",
+        "deepctl_cmd_completion",
+        "deepctl_cmd_debug",
+        "deepctl_cmd_debug_audio",
+        "deepctl_cmd_debug_browser",
+        "deepctl_cmd_debug_network",
+        "deepctl_cmd_debug_probe",
+        "deepctl_cmd_debug_toolkit",
+        "deepctl_cmd_ffprobe",
+        "deepctl_cmd_init",
+        "deepctl_cmd_keys",
+        "deepctl_cmd_listen",
+        "deepctl_cmd_login",
+        "deepctl_cmd_mcp",
+        "deepctl_cmd_members",
+        "deepctl_cmd_models",
+        "deepctl_cmd_plugin",
+        "deepctl_cmd_projects",
+        "deepctl_cmd_read",
+        "deepctl_cmd_requests",
+        "deepctl_cmd_skills",
+        "deepctl_cmd_speak",
+        "deepctl_cmd_transcribe",
+        "deepctl_cmd_update",
+        "deepctl_cmd_usage",
+        "deepctl_core",
+        "deepctl_shared_utils",
+        "deepctl_telemetry",
+    }
+)
+_KNOWN_PACKAGES = frozenset(
+    {
+        "anyio",
+        "certifi",
+        "click",
+        "deepgram",
+        "deepgram_mcp",
+        "h11",
+        "httpcore",
+        "httpx",
+        "keyring",
+        "mcp",
+        "platformdirs",
+        "pydantic",
+        "pydantic_core",
+        "requests",
+        "rich",
+        "sentry_sdk",
+        "typer",
+        "urllib3",
+        "websockets",
+        "yaml",
+    }
+)
+OTHER_NAME = "<other>"
+
+
+def _known_module(module: str) -> bool:
+    top = module.split(".", 1)[0]
+    return (
+        top in _FIRST_PARTY
+        or top in _KNOWN_PACKAGES
+        or top in getattr(sys, "stdlib_module_names", ())
+    )
+
+
+# Identifier-like tokens only. A value that doesn't match is dropped, never
+# escaped or truncated, so free text can't reach the payload.
+_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_.]{0,127}$")
+_FUNCTION_RE = re.compile(r"^(<[a-z]+>|[A-Za-z_][A-Za-z0-9_.<>]{0,127})$")
+_VERSION_RE = re.compile(r"^[A-Za-z0-9_.+-]{1,64}$")
+_COMMAND_RE = re.compile(r"^[A-Za-z0-9 _-]{1,200}$")
+_FLAGS_RE = re.compile(r"^[A-Za-z0-9,_-]{0,1000}$")
+
+
+def _match(pattern: re.Pattern[str], value: object) -> str | None:
+    return value if isinstance(value, str) and pattern.match(value) else None
+
+
+def _allowed_tags() -> dict[str, str]:
+    """Run-level fields: command path, flag names, version, OS, arch, Python."""
+    try:
+        from deepctl_core.telemetry_context import command_context
+
+        context = command_context()
+    except ImportError:
+        # An older deepctl-core without the context: report without cmd.*.
+        context = {}
+    candidates = {
+        "cmd.path": _match(_COMMAND_RE, context.get("command")),
+        "cmd.flags": _match(_FLAGS_RE, context.get("flags")),
+        "cli.os": _match(_VERSION_RE, platform.system()),
+        "cli.arch": _match(_VERSION_RE, platform.machine()),
+        "cli.python": _match(_VERSION_RE, platform.python_version()),
+    }
+    return {key: value for key, value in candidates.items() if value is not None}
+
+
+def _allowed_exception(exc: dict[str, Any]) -> dict[str, Any] | None:
+    """Exception type, mechanism, and module/function/line per frame.
+
+    Names from modules outside `_known_module` become OTHER_NAME, so a
+    plugin's or script's own identifiers are never sent.
+    """
+    exc_type = _match(_NAME_RE, exc.get("type"))
+    if exc_type is None:
+        return None
+    type_module = _match(_NAME_RE, exc.get("module")) or "builtins"
+    if not _known_module(type_module):
+        exc_type = OTHER_NAME
+
+    frames: list[dict[str, Any]] = []
+    for frame in (exc.get("stacktrace") or {}).get("frames") or []:
+        kept: dict[str, Any] = {}
+        module = _match(_NAME_RE, frame.get("module"))
+        function = _match(_FUNCTION_RE, frame.get("function"))
+        lineno = frame.get("lineno")
+        if module is None or not _known_module(module):
+            module = function = OTHER_NAME
+        kept["module"] = module
+        if function is not None:
+            kept["function"] = function
+        if isinstance(lineno, int) and not isinstance(lineno, bool):
+            kept["lineno"] = lineno
+        if kept:
+            frames.append(kept)
+
+    rebuilt: dict[str, Any] = {"type": exc_type}
+    mechanism = exc.get("mechanism") or {}
+    mechanism_type = _match(_NAME_RE, mechanism.get("type"))
+    if mechanism_type is not None:
+        rebuilt["mechanism"] = {"type": mechanism_type}
+        if isinstance(mechanism.get("handled"), bool):
+            rebuilt["mechanism"]["handled"] = mechanism["handled"]
+    if frames:
+        rebuilt["stacktrace"] = {"frames": frames}
+    return rebuilt
+
+
+def _rebuild_event(event: Event, _hint: Hint) -> Event | None:
+    """Build a new event from allowlisted fields; everything else is dropped.
+
+    The SDK's event is only read, never forwarded: messages, exception
+    values, paths, variables, request data, contexts, extra, modules,
+    breadcrumbs, user and server_name never make it into the new event.
+    Events without an exception (log messages, transactions) are dropped.
+
+    Also drops closed-stream events (see ``_is_broken_pipe``).
+    """
+    if _is_broken_pipe(event):
+        return None
+
+    values = [
+        rebuilt
+        for exc in (event.get("exception") or {}).get("values") or []
+        if (rebuilt := _allowed_exception(exc)) is not None
+    ]
+    if not values:
+        return None
+
+    rebuilt_event: dict[str, Any] = {
+        "platform": "python",
+        "level": "error",
+        "exception": {"values": values},
+        "tags": _allowed_tags(),
+    }
+    for key, pattern in (
+        ("event_id", re.compile(r"^[0-9a-f]{32}$")),
+        ("release", re.compile(r"^deepctl@[A-Za-z0-9_.+-]{1,64}$")),
+        ("environment", _NAME_RE),
+    ):
+        value = _match(pattern, event.get(key))
+        if value is not None:
+            rebuilt_event[key] = value
+    timestamp = event.get("timestamp")
+    if timestamp is not None:
+        rebuilt_event["timestamp"] = timestamp
+    sdk = event.get("sdk") or {}
+    sdk_name = _match(_NAME_RE, sdk.get("name"))
+    sdk_version = _match(_VERSION_RE, sdk.get("version"))
+    if sdk_name and sdk_version:
+        rebuilt_event["sdk"] = {"name": sdk_name, "version": sdk_version}
+    return rebuilt_event  # type: ignore[return-value]

deepctl_telemetry-0.0.8/src/deepctl_telemetry/notice.py

@@ -0,0 +1,106 @@
+"""Subtle telemetry notice appended to `--help` output."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import TYPE_CHECKING
+
+import click
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from deepctl_core import Config
+
+
+# Golden text, compared byte for byte with tests/golden/notice_*.txt.
+# NOTICE_ON shows only with a loopback DEEPCTL_TELEMETRY_DSN (tests and local
+# sinks). It names the three opt-outs that exist: the flag for one run, the env
+# var, and the config-file key.
+NOTICE_ON = (
+    "Telemetry is on: unexpected errors only, with no flag values, paths or "
+    "keys. Turn off: --no-telemetry, DEEPCTL_TELEMETRY_DISABLED=1, or "
+    "telemetry.enabled: false in config.yaml."
+)
+NOTICE_OFF = "Telemetry is off."
+# No destination (no loopback DEEPCTL_TELEMETRY_DSN), or the build switch is
+# off: what every user of this version sees.
+NOTICE_NONE = "This version of dg sends no telemetry."
+
+_installed = False
+# The latest fallback passed to install_help_notice (one per main() call).
+_fallback: list[Callable[[], Config]] = []
+
+
+def render_notice(config: Config) -> str:
+    """Return the one-line notice for the current telemetry state.
+
+    Dim only on a terminal with NO_COLOR unset; `click.style` doesn't check
+    either on its own.
+    """
+    from .client import _opt_out_source
+
+    source = _opt_out_source(config)
+    if source is None:
+        text = NOTICE_ON
+    elif source in ("build", "dsn"):
+        text = NOTICE_NONE
+    else:
+        text = NOTICE_OFF
+    if os.environ.get("NO_COLOR") or not _stdout_is_tty():
+        return text
+    return click.style(text, dim=True)
+
+
+def _stdout_is_tty() -> bool:
+    try:
+        return sys.stdout.isatty()
+    except Exception:
+        return False
+
+
+def _config_for_help(
+    ctx: click.Context, fallback_config: Callable[[], Config]
+) -> Config:
+    """The Config this run resolved, or the fallback for root-level help.
+
+    Subcommand help runs after the root callback has built the Config from
+    `--config`/`--profile`, so it is on the root context. Root-level
+    `--help` fires during option parsing, before that, so it uses the
+    fallback.
+    """
+    obj = ctx.find_root().obj
+    if isinstance(obj, dict) and obj.get("config") is not None:
+        config: Config = obj["config"]
+        return config
+    try:
+        return fallback_config()
+    except Exception:
+        from deepctl_core import Config
+
+        return Config()
+
+
+def install_help_notice(fallback_config: Callable[[], Config]) -> None:
+    """Monkey-patch Click so every `--help` ends with the telemetry notice.
+
+    Click formats help via `Command.get_help(ctx)`. We wrap that method
+    once at startup so every command (including subcommands and plugin
+    commands) picks up the footer without needing per-command wiring. The
+    notice is rendered when help is shown, so it reflects `--config` and
+    `--no-telemetry`.
+    """
+    global _installed
+    _fallback[:] = [fallback_config]
+    if _installed:
+        return
+
+    original_get_help = click.Command.get_help
+
+    def get_help_with_notice(self: click.Command, ctx: click.Context) -> str:
+        notice = render_notice(_config_for_help(ctx, _fallback[0]))
+        return original_get_help(self, ctx) + "\n\n" + notice
+
+    click.Command.get_help = get_help_with_notice  # type: ignore[method-assign]
+    _installed = True

{deepctl_telemetry-0.0.7 → deepctl_telemetry-0.0.8}/src/deepctl_telemetry.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: deepctl-telemetry
-Version: 0.0.7
-Summary: Opt-out phone-home telemetry for deepctl
+Version: 0.0.8
+Summary: Error reporting for deepctl; this version sends no telemetry
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>
 License-Expression: MIT
@@ -14,8 +14,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: deepctl-core>=0.1.10
-Requires-Dist: sentry-sdk>=2.0.0
+Requires-Dist: deepctl-core>=0.3.0
+Requires-Dist: sentry-sdk<3,>=2.35.0
 Requires-Dist: click>=8.0.0
 Requires-Dist: rich>=13.0.0
 
@@ -23,7 +23,7 @@ Requires-Dist: rich>=13.0.0
 
 > Part of [deepctl](https://github.com/deepgram/cli) — Official Deepgram CLI
 
-Opt-out phone-home telemetry for deepctl
+Error reporting for deepctl; this version sends no telemetry
 
 This package provides internal APIs for deepctl and its command packages. It is not intended for direct use.
 
@@ -50,7 +50,7 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `sentry-sdk>=2.0.0`
+- `sentry-sdk>=2.35.0,<3`
 - `click>=8.0.0`
 - `rich>=13.0.0`
 

deepctl_telemetry-0.0.8/src/deepctl_telemetry.egg-info/requires.txt

@@ -0,0 +1,4 @@
+deepctl-core>=0.3.0
+sentry-sdk<3,>=2.35.0
+click>=8.0.0
+rich>=13.0.0

deepctl_telemetry-0.0.7/src/deepctl_telemetry/__init__.py

@@ -1,13 +0,0 @@
-"""Opt-out phone-home telemetry for deepctl."""
-
-from .client import init_telemetry, is_enabled
-from .notice import install_help_notice, render_notice
-
-__all__ = [
-    "init_telemetry",
-    "install_help_notice",
-    "is_enabled",
-    "render_notice",
-]
-
-__version__ = "0.0.7"  # x-release-please-version

deepctl_telemetry-0.0.7/src/deepctl_telemetry/client.py

@@ -1,179 +0,0 @@
-"""Sentry-backed telemetry client with strict opt-out."""
-
-from __future__ import annotations
-
-import atexit
-import os
-import platform
-import sys
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from deepctl_core import Config
-    from sentry_sdk.types import Event, Hint
-
-
-SENTRY_DSN = (
-    "https://d7a2aabbf772218e3bbe89266999af70"
-    "@o206115.ingest.us.sentry.io/4510993603362816"
-)
-
-DSN_ENV_VAR = "DEEPCTL_TELEMETRY_DSN"
-DISABLE_ENV_VAR = "DEEPCTL_TELEMETRY_DISABLED"
-
-_initialized = False
-
-
-def is_enabled(config: Config) -> bool:
-    """Whether telemetry should phone home for this invocation.
-
-    Resolution order: env override (DEEPCTL_TELEMETRY_DISABLED=1 wins),
-    then the user's config (`telemetry.enabled`, default `True`).
-    """
-    if os.environ.get(DISABLE_ENV_VAR, "").lower() in {"1", "true", "yes"}:
-        return False
-    return bool(config.get("telemetry.enabled", True))
-
-
-def init_telemetry(config: Config) -> bool:
-    """Initialize the Sentry SDK if telemetry is enabled.
-
-    Idempotent — safe to call multiple times. Returns whether init ran.
-    """
-    global _initialized
-    if _initialized:
-        return True
-    if not is_enabled(config):
-        return False
-
-    dsn = os.environ.get(DSN_ENV_VAR) or SENTRY_DSN
-
-    try:
-        import sentry_sdk
-    except ImportError:
-        return False
-
-    try:
-        cli_version = _read_cli_version()
-    except Exception:
-        cli_version = "unknown"
-
-    sentry_sdk.init(
-        dsn=dsn,
-        release=f"deepctl@{cli_version}",
-        environment="production",
-        send_default_pii=False,
-        auto_session_tracking=True,
-        traces_sample_rate=1.0,
-        profiles_sample_rate=1.0,
-        enable_logs=True,
-        attach_stacktrace=True,
-        max_breadcrumbs=100,
-        before_send=_scrub_event,
-    )
-
-    sentry_sdk.set_tag("cli.os", platform.system().lower())
-    sentry_sdk.set_tag("cli.arch", platform.machine().lower())
-    sentry_sdk.set_tag(
-        "cli.python",
-        f"{sys.version_info.major}.{sys.version_info.minor}",
-    )
-    sentry_sdk.set_tag("cli.version", cli_version)
-
-    sentry_sdk.start_session()
-    atexit.register(_flush_on_exit)
-
-    _initialized = True
-    return True
-
-
-def _flush_on_exit() -> None:
-    """Flush queued envelopes before process exit (best-effort, 2s budget)."""
-    try:
-        import sentry_sdk
-
-        sentry_sdk.flush(timeout=2.0)
-    except Exception:
-        pass
-
-
-def _read_cli_version() -> str:
-    import importlib.metadata
-
-    return importlib.metadata.version("deepctl")
-
-
-_MCP_NOISE_LOGGERS = frozenset(
-    {
-        "mcp.client.streamable_http",
-        "mcp.server.lowlevel.server",
-    }
-)
-
-
-def _is_mcp_transient_noise(event: Event) -> bool:
-    """Identify log events from the MCP SDK that are not actionable bugs.
-
-    `dg mcp` embeds the upstream `mcp` Python SDK, which logs to Sentry via
-    the logging integration whenever the upstream MCP server returns 5xx
-    (handled by the client) or the stdio peer closes mid-message (handled by
-    the server). Both are recovered internally. Surfacing them as Sentry
-    issues just creates triage cost for the DX team and hides real CLI bugs.
-
-    Any unhandled exception is kept regardless of logger.
-    """
-    if (event.get("logger") or "") not in _MCP_NOISE_LOGGERS:
-        return False
-    for exc in (event.get("exception") or {}).get("values") or []:
-        mechanism = exc.get("mechanism") or {}
-        if mechanism.get("handled") is False:
-            return False
-    return True
-
-
-def _is_broken_pipe(event: Event) -> bool:
-    """Identify events caused by writing to a closed/broken output stream.
-
-    When `dg mcp` runs as an MCP server, the host can close stdio while the
-    CLI is still finishing up. Any residual write (an advisory notification, a
-    console error message) then raises ``BrokenPipeError`` — or rich's
-    ``ValueError: I/O operation on closed file`` when the underlying stream is
-    already closed. Neither is an actionable CLI bug, so drop them rather than
-    page the DX team.
-    """
-    for exc in (event.get("exception") or {}).get("values") or []:
-        exc_type = exc.get("type") or ""
-        if exc_type == "BrokenPipeError":
-            return True
-        if exc_type == "ValueError" and "closed file" in (exc.get("value") or ""):
-            return True
-    return False
-
-
-def _scrub_event(event: Event, _hint: Hint) -> Event | None:
-    """Drop request bodies, headers, and any user-identifying data.
-
-    Sentry SDK already filters most PII via send_default_pii=False, but
-    Auth tokens, project IDs, and file paths can still leak through
-    breadcrumbs and exception messages. This is a defense-in-depth scrub.
-
-    Also drops known-noise events (see ``_is_mcp_transient_noise`` and
-    ``_is_broken_pipe``).
-    """
-    if _is_mcp_transient_noise(event) or _is_broken_pipe(event):
-        return None
-
-    request: dict[str, Any] = event.get("request") or {}
-    if "headers" in request:
-        request["headers"] = {}
-    if "cookies" in request:
-        request["cookies"] = {}
-    if "data" in request:
-        request["data"] = "[Filtered]"
-
-    user: dict[str, Any] = event.get("user") or {}
-    user.pop("email", None)
-    user.pop("ip_address", None)
-    user.pop("username", None)
-
-    return event

deepctl_telemetry-0.0.7/src/deepctl_telemetry/notice.py

@@ -1,51 +0,0 @@
-"""Subtle telemetry notice appended to `--help` output."""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-import click
-
-if TYPE_CHECKING:
-    from deepctl_core import Config
-
-
-# There is no `dg config` command, so the notice names the two opt-outs that
-# actually exist: the env var for one run, and the config file to persist it.
-NOTICE_ON = (
-    "Telemetry is on (anonymous error reports). "
-    "Disable: DEEPCTL_TELEMETRY_DISABLED=1, "
-    "or set telemetry.enabled: false in your deepctl config.yaml"
-)
-NOTICE_OFF = "Telemetry is off."
-
-_installed = False
-
-
-def render_notice(config: Config) -> str:
-    """Return the dim one-line notice for the current telemetry state."""
-    from .client import is_enabled
-
-    text = NOTICE_ON if is_enabled(config) else NOTICE_OFF
-    return click.style(text, dim=True)
-
-
-def install_help_notice(config: Config) -> None:
-    """Monkey-patch Click so every `--help` ends with the telemetry notice.
-
-    Click formats help via `Command.get_help(ctx)`. We wrap that method
-    once at startup so every command (including subcommands and plugin
-    commands) picks up the footer without needing per-command wiring.
-    """
-    global _installed
-    if _installed:
-        return
-
-    original_get_help = click.Command.get_help
-    notice = render_notice(config)
-
-    def get_help_with_notice(self: click.Command, ctx: click.Context) -> str:
-        return original_get_help(self, ctx) + "\n\n" + notice
-
-    click.Command.get_help = get_help_with_notice  # type: ignore[method-assign]
-    _installed = True

deepctl_telemetry-0.0.7/src/deepctl_telemetry.egg-info/requires.txt

@@ -1,4 +0,0 @@
-deepctl-core>=0.1.10
-sentry-sdk>=2.0.0
-click>=8.0.0
-rich>=13.0.0