fix(telemetry): honor opt-out env vars without contacting PostHog 🤖🤖🤖🤖 (#2787)

* fix(telemetry): honor opt-out env vars without contacting PostHog

Re-read GISKARD_TELEMETRY_DISABLED and DO_NOT_TRACK on capture (including
cwd .env and quoted values), and pass send=False so a firewalled process
never opens eu.i.posthog.com after opt-out.

Co-authored-by: Kevin Messiaen <kevinmessiaen@users.noreply.github.com>

* simplify code

* add more tests

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Kevin Messiaen <kevinmessiaen@users.noreply.github.com>
Co-authored-by: Henrique Chaves <44180294+henchaves@users.noreply.github.com>
Co-authored-by: Henrique Chaves <henrique@giskard.ai>

Author: 3 people

README.md

@@ -44,7 +44,7 @@ Requires Python 3.12+.
 | `openai` / `anthropic` / … | provider SDKs (see `pyproject.toml` optional deps) |
 
 **Telemetry:** optional aggregated analytics via `giskard-core`. No prompts or outputs are sent.
-Opt out **before importing Giskard**: `export DO_NOT_TRACK=1` or `export GISKARD_TELEMETRY_DISABLED=1`.
+Opt out with `export DO_NOT_TRACK=1` or `export GISKARD_TELEMETRY_DISABLED=1` (or the same keys in a `.env` file in the working directory). Set them before import to skip creating `~/.giskard/id`; setting them later still stops further sends.
 Details: [`giskard-core` README](libs/giskard-core/README.md#telemetry).
 
 ---

libs/giskard-core/README.md

@@ -31,11 +31,13 @@ A random **persistent ID** may be stored under `~/.giskard/id` so repeated sessi
 
 ### How to disable telemetry
 
-Set any of these environment variables to a truthy value **before** importing `giskard` packages (values are matched case-insensitively; common examples: `1`, `true`, `yes`, `on`):
+Set any of these environment variables to a truthy value (matched case-insensitively; wrapping quotes are ignored; common examples: `1`, `true`, `yes`, `on`):
 
 - `DO_NOT_TRACK`
 - `GISKARD_TELEMETRY_DISABLED`
 
+Flags are read from the **process environment** and from a **`.env` file in the working directory** (process env wins). Set them **before importing** Giskard packages to skip creating `~/.giskard/id` and to never start the analytics sender. If you set them later, further events are dropped and the sender is stopped so **no requests are made** to PostHog (including in environments that block `eu.i.posthog.com`).
+
 You can also call `disable_telemetry()` from `giskard.core` at runtime to turn off further sends for that process (for example from test harnesses). That does not remove `~/.giskard/id` if it was already created; use env-based opt-out before import to avoid writing the file.
 
 ```python
@@ -48,7 +50,7 @@ disable_telemetry()
 
 When telemetry is **enabled**, PostHog may apply **GeoIP** enrichment to events (server-side location metadata used in dashboards). That enrichment is **off** whenever telemetry is fully disabled (see above) or when you call `disable_telemetry()`.
 
-To **keep usage analytics** but **disable GeoIP only**, set this environment variable to a truthy value **before** importing Giskard packages (same matching rules as in [How to disable telemetry](#how-to-disable-telemetry)):
+To **keep usage analytics** but **disable GeoIP only**, set this environment variable to a truthy value (same matching rules and `.env` behavior as in [How to disable telemetry](#how-to-disable-telemetry)):
 
 - `GISKARD_TELEMETRY_DISABLE_GEOIP`
 

libs/giskard-core/src/giskard/core/telemetry/telemetry.py

@@ -1,7 +1,9 @@
 import asyncio
+import atexit
 import contextvars
 import functools
 import os
+import re
 import sys
 import uuid
 from collections.abc import Callable, Iterator
@@ -20,15 +22,42 @@
 _DISABLE_GEOIP_ENV_VARS = [
     "GISKARD_TELEMETRY_DISABLE_GEOIP",
 ]
+_OPT_OUT_ENV_KEYS = frozenset((*_DISABLING_ENV_VARS, *_DISABLE_GEOIP_ENV_VARS))
+
+
+def _dotenv_flags() -> dict[str, str]:
+    """Opt-out flags from a cwd ``.env``, the file giskard.checks settings already read.
+
+    Minimal dotenv rules: ``export`` prefixes and unquoted `` # comment`` tails
+    are dropped; ``errors="replace"`` so a non-UTF-8 file cannot abort import.
+    """
+    try:
+        text = Path(".env").read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return {}
+    flags: dict[str, str] = {}
+    for line in text.lstrip("\ufeff").splitlines():
+        key, sep, value = line.strip().removeprefix("export ").partition("=")
+        if sep and key.strip() in _OPT_OUT_ENV_KEYS:
+            flags[key.strip()] = re.sub(r"\s+#.*", "", value).strip()
+    return flags
+
+
+def _flag_is_true(name: str) -> bool:
+    """True if ``name`` is truthy in the process env, else in cwd ``.env``."""
+    value = os.environ.get(name)
+    if value is None:
+        value = _dotenv_flags().get(name)
+    return value is not None and is_true_env_str(value.strip().strip("'\""))
 
 
 def _should_disable() -> bool:
-    return any(is_true_env_str(os.getenv(var)) for var in _DISABLING_ENV_VARS)
+    return any(_flag_is_true(var) for var in _DISABLING_ENV_VARS)
 
 
 def _should_disable_geoip() -> bool:
     return _should_disable() or any(
-        is_true_env_str(os.getenv(var)) for var in _DISABLE_GEOIP_ENV_VARS
+        _flag_is_true(var) for var in _DISABLE_GEOIP_ENV_VARS
     )
 
 
@@ -118,20 +147,40 @@ def _get_or_create_anonymous_id() -> str | None:
 # dashboards, while _anonymous_id keeps them all linked to the same user.
 _process_session_id = str(uuid.uuid4())
 
+# send=False when opted out: no consumer thread, no atexit join, no HTTP,
+# so a firewalled ``eu.i.posthog.com`` is never contacted.
+_disabled_at_import = _should_disable()
 telemetry = Posthog(
     project_api_key="phc_Asp36pe4X5WMqeJ4aMMV4gq5LGdGw69mdYSdEYGpbxm2",  # pragma: allowlist secret
     host="https://eu.i.posthog.com",
-    disabled=_should_disable(),
+    disabled=_disabled_at_import,
     disable_geoip=_should_disable_geoip(),
+    send=not _disabled_at_import,
 )
 
 
 def disable_telemetry() -> None:
-    """
-    Disable telemetry. Overrides the environment variable settings.
+    """Disable telemetry for this process, overriding the environment variables.
+
+    One-way. Stops the PostHog sender so no further requests reach the
+    analytics host. Does not remove ``~/.giskard/id`` if it was already created.
     """
     telemetry.disabled = True
     telemetry.disable_geoip = True
+    telemetry.send = False
+    for consumer in telemetry.consumers or []:
+        consumer.pause()
+    # Consumers are daemon threads; with the atexit join unregistered they
+    # cannot delay exit on uploads to a blocked host.
+    atexit.unregister(telemetry.join)
+
+
+def _apply_env_opt_out() -> None:
+    """Honor opt-out flags set after import (notebooks, ``.env``); one-way."""
+    if _should_disable():
+        disable_telemetry()
+    elif _should_disable_geoip():
+        telemetry.disable_geoip = True
 
 
 # Tracks whether we are currently inside any telemetry scope.
@@ -160,7 +209,8 @@ def telemetry_capture(
     properties : dict[str, object] or None
         Optional event properties, passed through to PostHog unchanged.
     """
-    if not _in_telemetry_scope.get():
+    _apply_env_opt_out()
+    if telemetry.disabled or not _in_telemetry_scope.get():
         return
     _ = telemetry.capture(event, properties=properties)
 
@@ -176,6 +226,7 @@ def telemetry_run_context() -> Iterator[None]:
     is_outermost = not _in_telemetry_scope.get()
     token = _in_telemetry_scope.set(True)
     try:
+        _apply_env_opt_out()
         with telemetry.new_context(capture_exceptions=False):
             if _anonymous_id is not None:
                 identify_context(_anonymous_id)