scope-analytics 0.1.4__tar.gz → 0.1.5__tar.gz

{scope_analytics-0.1.4/scope_analytics.egg-info → scope_analytics-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scope-analytics
-Version: 0.1.4
+Version: 0.1.5
 Summary: AI-powered analytics SDK for backend applications with automatic LLM tracking
 Home-page: https://scopeai.dev
 Author: Scope AI
@@ -27,6 +27,8 @@ Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
 Requires-Dist: requests>=2.25.0; extra == "dev"
 Requires-Dist: aiohttp>=3.8.0; extra == "dev"
 Requires-Dist: httpx2>=2.0.0; extra == "dev"
+Requires-Dist: gunicorn>=20.0; extra == "dev"
+Requires-Dist: flask>=2.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: flake8>=6.0.0; extra == "dev"
 Provides-Extra: openai
@@ -91,15 +93,24 @@ export SCOPE_API_KEY="sk_live_..."
 # Instead of:   uvicorn main:app --reload
 # Run:          scope-run uvicorn main:app --reload
 
-# Instead of:   gunicorn app:app -w 4
+# Instead of:   gunicorn app:app -w 4                                   (Flask, Django)
 # Run:          scope-run gunicorn app:app -w 4
 
+# Instead of:   gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker  (FastAPI; pip install uvicorn-worker)
+# Run:          scope-run gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker
+
 # Instead of:   flask run --port 5000
 # Run:          scope-run flask run --port 5000
 ```
 
 That's it! Your LLM calls are now automatically tracked AND correlated
-with frontend sessions (for FastAPI, Flask, Django).
+with frontend sessions (for FastAPI, Flask, Django). Workers forked by gunicorn or
+Celery ship on their own timer (0.1.5). LangChain / LangGraph, LlamaIndex, PydanticAI,
+Instructor and the OpenAI Agents SDK are captured through the SDK they call
+(LangChain needs 0.1.5).
+
+**Serverless / notebooks** — no start command to prefix: create `scope = ScopeAnalytics()`
+at module import and call `scope.flush(timeout=2.0)` before the handler returns (0.1.5).
 
 ### Option B: Code-Based Installation
 
@@ -176,6 +187,7 @@ scope-run --dry-run uvicorn main:app
 | `SCOPE_DEBUG` | No | Set to 'true' for debug logging |
 | `SCOPE_ENVIRONMENT` | No | Environment name (default: production) |
 | `SCOPE_CAPTURE_HTTP` | No | Capture outbound calls to other services (default: on; `false` turns it off) |
+| `HTTPS_PROXY` / `NO_PROXY` / `SSL_CERT_FILE` | No | Honoured for the SDK's own connection to Scope (read from the environment only) |
 
 ## Configuration (Code-Based)
 
@@ -230,8 +242,7 @@ def my_request_handler(request):
 Add the frontend SDK to link user interactions with backend LLM calls:
 
 ```html
-<script src="https://cdn.scopeai.dev/v1/sdk.js"
-        data-api-key="pk_live_your_public_key"></script>
+<script src="https://cdn.scopeai.dev/v1/sdk.js?token=pk_live_your_public_key" async></script>
 ```
 
 The frontend SDK automatically:

{scope_analytics-0.1.4 → scope_analytics-0.1.5}/README.md

@@ -38,15 +38,24 @@ export SCOPE_API_KEY="sk_live_..."
 # Instead of:   uvicorn main:app --reload
 # Run:          scope-run uvicorn main:app --reload
 
-# Instead of:   gunicorn app:app -w 4
+# Instead of:   gunicorn app:app -w 4                                   (Flask, Django)
 # Run:          scope-run gunicorn app:app -w 4
 
+# Instead of:   gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker  (FastAPI; pip install uvicorn-worker)
+# Run:          scope-run gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker
+
 # Instead of:   flask run --port 5000
 # Run:          scope-run flask run --port 5000
 ```
 
 That's it! Your LLM calls are now automatically tracked AND correlated
-with frontend sessions (for FastAPI, Flask, Django).
+with frontend sessions (for FastAPI, Flask, Django). Workers forked by gunicorn or
+Celery ship on their own timer (0.1.5). LangChain / LangGraph, LlamaIndex, PydanticAI,
+Instructor and the OpenAI Agents SDK are captured through the SDK they call
+(LangChain needs 0.1.5).
+
+**Serverless / notebooks** — no start command to prefix: create `scope = ScopeAnalytics()`
+at module import and call `scope.flush(timeout=2.0)` before the handler returns (0.1.5).
 
 ### Option B: Code-Based Installation
 
@@ -123,6 +132,7 @@ scope-run --dry-run uvicorn main:app
 | `SCOPE_DEBUG` | No | Set to 'true' for debug logging |
 | `SCOPE_ENVIRONMENT` | No | Environment name (default: production) |
 | `SCOPE_CAPTURE_HTTP` | No | Capture outbound calls to other services (default: on; `false` turns it off) |
+| `HTTPS_PROXY` / `NO_PROXY` / `SSL_CERT_FILE` | No | Honoured for the SDK's own connection to Scope (read from the environment only) |
 
 ## Configuration (Code-Based)
 
@@ -177,8 +187,7 @@ def my_request_handler(request):
 Add the frontend SDK to link user interactions with backend LLM calls:
 
 ```html
-<script src="https://cdn.scopeai.dev/v1/sdk.js"
-        data-api-key="pk_live_your_public_key"></script>
+<script src="https://cdn.scopeai.dev/v1/sdk.js?token=pk_live_your_public_key" async></script>
 ```
 
 The frontend SDK automatically:

{scope_analytics-0.1.4 → scope_analytics-0.1.5}/scope_analytics/__init__.py

@@ -5,6 +5,7 @@ AI-powered analytics with automatic LLM conversation tracking
 
 import atexit
 import logging
+import sys
 from typing import Optional
 
 from .config import ScopeConfig, DEFAULT_REDACT_PATTERNS
@@ -45,7 +46,7 @@ def _resolve_version() -> str:
 
 __version__ = _resolve_version()
 __all__ = [
-    "ScopeAnalytics",
+    "ScopeAnalytics",               # .flush(timeout=) ships queued events now (serverless, notebooks)
     "ScopeContext",
     "ScopeConfig",
     "DEFAULT_REDACT_PATTERNS",      # default credential-scrub patterns (on by default; [] to opt out)
@@ -184,6 +185,7 @@ class ScopeAnalytics:
             flush_callback=self._flush_events,
             config=self.config,
             event_enricher=self.deployment.stamp,
+            on_fork=self._after_fork,
         )
 
         # Initialize patchers
@@ -200,10 +202,16 @@ class ScopeAnalytics:
         # in it would claim LLM coverage this SDK does not have.
         self.outbound_http_libraries = []
         self._llm_sdks_detected = []  # Recognized SDKs whose import succeeded (≠ patched)
+        self._celery_hooked = False
 
         # Start queue background thread
         self.queue.start()
 
+        # A Celery worker already loaded? Then the prefork children's shutdown signal
+        # flushes their last batch (see _connect_celery_shutdown). Workers started through
+        # scope-run load Celery AFTER this point; the fork hook connects it in each child.
+        self._connect_celery_shutdown()
+
         # Register shutdown hook
         atexit.register(self.shutdown)
 
@@ -380,6 +388,87 @@ class ScopeAnalytics:
             # Coverage reporting must never break startup.
             self.config.log(f"Coverage-gap check failed: {e}")
 
+    def _after_fork(self):
+        """Runs in a forked CHILD once the queue has restarted its flush thread there.
+        The inherited ship client shares its pooled sockets with the parent — two
+        processes writing one TCP connection interleave bytes — so the child gets its
+        own. The background session id is per process, so the child mints its own. And
+        a Celery child flushes on its own shutdown signal (see _connect_celery_shutdown)."""
+        try:
+            # The inherited client is dropped, never closed: httpx's pool close() takes
+            # the pool's thread lock, and if the parent's flush thread held it at the
+            # instant of the fork the child would block forever inside this hook (the
+            # thread that holds it does not exist here). Unreferenced, the sockets close
+            # by garbage collection, which takes no pool lock.
+            self.client = ScopeAPIClient(self.config)
+        except Exception as e:  # noqa: BLE001 - never let a fork hook break the child
+            self.config.log(f"Could not rebuild the ship client after fork: {e}")
+        ScopeContext.reset_background_session()
+        # A receiver connected in the parent is inherited and works here (it closes over
+        # this same instance), so connect only if nothing was connected before the fork
+        # — e.g. the scope-run path, where Celery was not yet imported at init.
+        self._connect_celery_shutdown()
+
+    def _connect_celery_shutdown(self):
+        """Celery's prefork children exit through os._exit(), which skips atexit — so
+        their last partial batch (under batch_size, under batch_timeout) would be lost.
+        When Celery is loaded (checked in sys.modules; never imported here to find out),
+        the child's ``worker_process_shutdown`` signal flushes with a hard two-second
+        limit, so a broken network can never hold a worker's shutdown."""
+        if self._celery_hooked or "celery" not in sys.modules:
+            return
+        try:
+            from celery import signals
+        except Exception:  # noqa: BLE001 - a half-imported celery is not ours to break
+            return
+
+        def _on_worker_process_shutdown(**_kwargs):
+            self.flush(timeout=2.0)
+
+        # Celery holds signal receivers weakly by default; keep a strong reference.
+        self._celery_shutdown_handler = _on_worker_process_shutdown
+        try:
+            signals.worker_process_shutdown.connect(_on_worker_process_shutdown, weak=False)
+            self._celery_hooked = True
+            self.config.log("Celery worker_process_shutdown hook connected")
+        except Exception as e:  # noqa: BLE001
+            self.config.log(f"Could not connect the Celery shutdown hook: {e}")
+
+    def flush(self, timeout: Optional[float] = None):
+        """
+        Ship every queued event now.
+
+        For the places the background timer can't be trusted to fire: a serverless
+        handler about to be frozen, a notebook cell, a worker process about to exit.
+        Without ``timeout`` the events are shipped on the calling thread and the call
+        returns when they are delivered (the client's normal request timeout applies).
+        With ``timeout`` the call returns within that many seconds whatever the network
+        does: the delivery runs on a helper thread with that limit per request and the
+        caller waits for it only until the deadline, so a slow batch still lands if the
+        process lives on, and a stuck one never holds the caller past the budget.
+        Batches already in flight on the batch-size path are waited for within the same
+        budget. Capture stays live afterwards — unlike shutdown(), which also unpatches.
+
+        Args:
+            timeout: Optional hard limit, in seconds, on how long this call may take.
+        """
+        if not self.enabled:
+            return
+        if timeout is None:
+            self.queue.flush(synchronous=True)
+            self.queue.wait_inflight(self.client.ship_timeout or 30.0)
+            return
+        import threading
+        import time
+        deadline = time.monotonic() + timeout
+        worker = threading.Thread(
+            target=self.queue.flush, kwargs={"synchronous": True, "timeout": timeout},
+            daemon=True, name="ScopeAnalytics-Flush",
+        )
+        worker.start()
+        worker.join(max(0.0, deadline - time.monotonic()))
+        self.queue.wait_inflight(max(0.0, deadline - time.monotonic()))
+
     def track_event(self, event_type: str, properties: dict):
         """
         Manually track an event
@@ -409,6 +498,11 @@ class ScopeAnalytics:
         # libraries — was silently dropped at validation.
         from datetime import datetime, timezone
         event.setdefault("timestamp", datetime.now(timezone.utc).isoformat())
+        # The two stamps every auto-captured event carries, so a manual event is the same
+        # to the SDK-status and environment views (a manual-only install used to show no
+        # version at all).
+        event.setdefault("sdk_version", self.config.sdk_version)
+        event.setdefault("environment", self.config.environment)
         if "session_id" not in event:
             # generate_temp (NOT ensure_session_id): ensure_ would PIN the temp id
             # into the contextvar as a side effect — in a long-lived worker with no
@@ -478,15 +572,19 @@ class ScopeAnalytics:
             if traits:
                 self.config.log(f"User traits: {traits}")
 
-    def _flush_events(self, events: list):
+    def _flush_events(self, events: list, timeout: Optional[float] = None):
         """
         Callback for flushing events to API
         Called by event queue when batch is ready
 
         Args:
             events: List of events to flush
+            timeout: Per-request limit for this batch only (set by ``flush(timeout=)``)
         """
-        success = self.client.ship_events(events)
+        # The limit is passed on only when set, so a one-argument stand-in for ship_events
+        # (tests, custom sinks) keeps working.
+        success = (self.client.ship_events(events) if timeout is None
+                   else self.client.ship_events(events, timeout=timeout))
 
         if not success:
             self.config.log(f"⚠️ Failed to ship {len(events)} events")

{scope_analytics-0.1.4 → scope_analytics-0.1.5}/scope_analytics/cli.py

@@ -21,6 +21,7 @@ Environment Variables:
 
 import os
 import sys
+import shutil
 import subprocess
 import argparse
 import tempfile
@@ -88,8 +89,31 @@ import os
 if os.environ.get('SCOPE_AUTO_INSTRUMENT') == 'true':
     try:
         import scope_analytics.auto
-    except ImportError:
-        pass  # scope-analytics not installed, skip silently
+        _launcher = os.environ.get('SCOPE_RUN_VERSION')
+        _running = getattr(scope_analytics, '__version__', None)
+        if _launcher and _running and _launcher != _running:
+            # The app's interpreter found a DIFFERENT copy of scope-analytics than the one
+            # scope-run was launched from (a global uvicorn next to an un-activated venv is
+            # the usual shape). That copy is what instruments the app; say so.
+            import sys
+            print(
+                "[Scope SDK] scope-run is scope-analytics " + _launcher + " but the interpreter "
+                "running your app (" + sys.executable + ") imported scope-analytics " + _running
+                + " — that copy is what instruments the app. To run " + _launcher + " here: "
+                + sys.executable + " -m pip install scope-analytics==" + _launcher,
+                file=sys.stderr,
+            )
+    except ImportError as e:
+        # The interpreter running the app is not the one scope-analytics was installed into
+        # (a pyenv shim, a system python, a multi-stage image). The user ran scope-run to be
+        # instrumented, so silence here would be the worst outcome: say it, once, loudly.
+        import sys
+        print(
+            "[Scope SDK] scope-analytics could not be imported by this interpreter ("
+            + sys.executable + "): " + str(e) + " — NOTHING is instrumented. Install it for "
+            "this interpreter: " + sys.executable + " -m pip install scope-analytics",
+            file=sys.stderr,
+        )
     except Exception as e:
         import sys
         print(f"[Scope SDK] Warning: Auto-instrumentation failed: {e}", file=sys.stderr)
@@ -187,6 +211,38 @@ Environment Variables:
     env = os.environ.copy()
     env['SCOPE_AUTO_INSTRUMENT'] = 'true'
 
+    # The command is resolved on PATH, so scope-run invoked from a virtualenv that is not
+    # activated (its absolute path in a Procfile, a Dockerfile, a systemd unit) used to
+    # launch whatever `uvicorn` / `gunicorn` came first on PATH — a different interpreter
+    # with a different scope-analytics, or none — and nothing said so. The launcher's own
+    # bin directory goes first, which is exactly what activating the virtualenv does; and
+    # the sitecustomize compares this version with the one the app's interpreter imports,
+    # saying so on stderr if they differ.
+    launcher_bin = os.path.dirname(os.path.abspath(sys.executable))
+    env['PATH'] = launcher_bin + os.pathsep + env.get('PATH', '')
+    version = _get_version()
+    if version != 'unknown' and not version.startswith('0.0.0'):
+        env['SCOPE_RUN_VERSION'] = version
+
+    # macOS: a Python process that runs a thread (the SDK's flush thread) and then forks
+    # workers — gunicorn, Celery's prefork pool, multiprocessing — trips the Objective-C
+    # runtime's fork-safety check in every child the first time it touches a system
+    # framework (the app's own HTTP client doing its proxy lookup is enough), and the child
+    # aborts: "+[NSCharacterSet initialize] may have been in progress in another thread when
+    # fork() was called". Measured with `scope-run gunicorn -w 2`: 0 of 10 runs healthy
+    # without this, 8 of 8 with it. This variable is the documented remedy for Python-and-fork
+    # on macOS; it means nothing anywhere else, so a Linux deployment is untouched. A value
+    # the user already set wins — and when scope-run sets it, it says so: nothing silent.
+    if sys.platform == 'darwin' and 'OBJC_DISABLE_INITIALIZE_FORK_SAFETY' not in env:
+        env['OBJC_DISABLE_INITIALIZE_FORK_SAFETY'] = 'YES'
+        print(
+            "[Scope SDK] macOS: set OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES for this command — "
+            "without it a server that forks workers (gunicorn, Celery) aborts in every child on "
+            "macOS's Objective-C fork-safety check. Set the variable yourself, to any value, to "
+            "choose otherwise.",
+            file=sys.stderr,
+        )
+
     if args.debug:
         env['SCOPE_DEBUG'] = 'true'
 
@@ -211,6 +267,7 @@ Environment Variables:
         print("[Scope SDK] Dry run - would execute:")
         print(f"  SCOPE_AUTO_INSTRUMENT=true")
         print(f"  PYTHONPATH={env['PYTHONPATH']}")
+        print(f"  {executable} resolves to: {shutil.which(executable, path=env['PATH']) or '(not found on PATH)'}")
         if args.debug:
             print(f"  SCOPE_DEBUG=true")
         print(f"  {' '.join(final_command)}")

scope_analytics-0.1.5/scope_analytics/client.py

@@ -0,0 +1,241 @@
+"""
+HTTP client for shipping events to Scope Analytics API
+Handles async communication with the backend API
+"""
+
+import json
+import os
+import ssl
+import urllib.request
+from urllib.parse import urlsplit
+
+import httpx
+from typing import List, Dict, Any, Optional
+
+from .context import ScopeContext
+
+
+class ScopeAPIClient:
+    """
+    Async HTTP client for Scope Analytics API
+
+    Handles:
+    - Event shipping to /api/events endpoint
+    - Authentication with secret API key
+    - Retry logic with exponential backoff
+    - Error handling
+    """
+
+    def __init__(self, config):
+        """
+        Initialize API client
+
+        Args:
+            config: SDK configuration
+        """
+        self.config = config
+        self.endpoint = f"{config.endpoint}/api/events"
+
+        # Per-request timeout override; shutdown sets this to a small value so the
+        # final synchronous flush can't hold process exit for the full 30s.
+        self.ship_timeout = None
+
+        # Discard reasons already said (see _note_discard) — once each, not per batch.
+        self._warned_discard_reasons = set()
+
+        # Create HTTP client
+        self.client = self._build_http_client(config)
+
+        self.config.log(f"API client initialized: {self.endpoint}")
+
+    @staticmethod
+    def ship_settings(endpoint: str) -> Dict[str, Any]:
+        """What the ship client takes from the environment: the proxy for the endpoint's
+        scheme (``HTTPS_PROXY`` / ``HTTP_PROXY`` / ``ALL_PROXY``, with ``NO_PROXY`` honoured)
+        and a custom CA bundle (``SSL_CERT_FILE`` / ``SSL_CERT_DIR``). Read from the
+        environment ONLY — never from the operating system's proxy service — see
+        _build_http_client for why. Pure, so it can be tested without a client."""
+        parts = urlsplit(endpoint)
+        proxies = urllib.request.getproxies_environment()
+        proxy = proxies.get(parts.scheme) or proxies.get("all")
+        if proxy and urllib.request.proxy_bypass_environment(parts.hostname or "", proxies):
+            proxy = None
+        return {
+            "proxy": proxy or None,
+            "cafile": os.environ.get("SSL_CERT_FILE") or None,
+            "capath": os.environ.get("SSL_CERT_DIR") or None,
+        }
+
+    @classmethod
+    def _build_http_client(cls, config) -> httpx.Client:
+        """Scope's own ship client, configured from the environment WITHOUT asking the
+        operating system for its proxy settings.
+
+        httpx's default (``trust_env=True``) resolves proxies through urllib's
+        ``getproxies()``, which on macOS falls through to the system proxy service when no
+        ``*_proxy`` variable is set. That call leaves CoreFoundation state behind that is
+        not fork-safe: a server that forks its workers after this SDK initialised in the
+        master (gunicorn without --preload) then had every worker crash inside the SAME
+        lookup — made by the app's own OpenAI/Anthropic client — intermittently. So the
+        three things ``trust_env`` would read are read here directly (proxies, NO_PROXY, a
+        custom CA bundle) and the OS proxy service is never consulted. The fourth,
+        ``.netrc``, does not apply: every request carries the Bearer header."""
+        settings = cls.ship_settings(config.endpoint)
+        verify: Any = True
+        if settings["cafile"] or settings["capath"]:
+            verify = ssl.create_default_context(cafile=settings["cafile"], capath=settings["capath"])
+        transport_kwargs: Dict[str, Any] = {"verify": verify}
+        if settings["proxy"]:
+            transport_kwargs["proxy"] = httpx.Proxy(settings["proxy"])
+        return httpx.Client(
+            timeout=30.0,
+            headers={
+                "Authorization": f"Bearer {config.api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": f"scope-analytics-python/{config.sdk_version}",
+            },
+            trust_env=False,
+            transport=httpx.HTTPTransport(**transport_kwargs),
+        )
+
+    def ship_events(self, events: List[Dict[str, Any]], timeout: Optional[float] = None) -> bool:
+        """
+        Ship batch of events to API
+
+        Args:
+            events: List of event dictionaries
+            timeout: Per-request limit for THIS call only (``flush(timeout=)``); None means
+                the client's own ``ship_timeout`` (None there = httpx's default).
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not events:
+            return True
+
+        # Shipping is Scope's OWN outbound HTTP. The marker below is what stops the
+        # outbound-HTTP patcher from capturing this POST — which would enqueue an event,
+        # which would trigger another POST, forever. It is set HERE rather than at the
+        # queue because this method is also called directly by the final shutdown flush,
+        # and because a contextvar set on the caller's thread would not be visible on the
+        # queue's background thread (contexts do not cross threads); setting it inside the
+        # call means it is always set on whichever thread is actually shipping.
+        with ScopeContext.scope_internal():
+            return self._ship(events, timeout)
+
+    def _ship(self, events: List[Dict[str, Any]], timeout: Optional[float] = None) -> bool:
+        try:
+            self.config.log(f"Shipping {len(events)} events to {self.endpoint}")
+
+            # Prepare payload
+            payload = {
+                "events": events,
+                "source": self.config.sdk_source,
+            }
+
+            # Strict-first serialization with a LOUD lossy fallback: events are
+            # sanitized at build time, so the strict path should always win — but a
+            # single stray non-JSON value must degrade to its string form (with a
+            # warning), never lose the whole batch.
+            try:
+                body = json.dumps(payload)
+            except (TypeError, ValueError):
+                body = json.dumps(payload, default=str)
+                self.config.warn(
+                    "Non-JSON value in event batch — coerced via str(). "
+                    "This indicates an event-sanitization gap; please report it."
+                )
+
+            # Send POST request
+            kwargs = {"content": body}
+            limit = timeout if timeout is not None else self.ship_timeout
+            if limit is not None:
+                kwargs["timeout"] = limit
+            response = self.client.post(self.endpoint, **kwargs)
+
+            # Check response
+            if response.status_code == 200:
+                self._note_discard(response, len(events))
+                self.config.log(f"✅ Successfully shipped {len(events)} events")
+                return True
+            else:
+                self.config.log(
+                    f"❌ Failed to ship events: HTTP {response.status_code} - {response.text}"
+                )
+                return False
+
+        except httpx.TimeoutException:
+            self.config.log("❌ Request timeout while shipping events")
+            return False
+
+        except httpx.HTTPError as e:
+            self.config.log(f"❌ HTTP error while shipping events: {e}")
+            return False
+
+        except Exception as e:
+            self.config.log(f"❌ Unexpected error while shipping events: {e}")
+            return False
+
+    def _note_discard(self, response, count: int) -> None:
+        """A 200 can still mean "received and thrown away": the ingest service answers
+        ``{"status": "discarded", "reason": ...}`` for a batch it will not keep — an IP the
+        project excludes, for instance. Reading only the status code made such batches
+        vanish without a word (the SDK logged "shipped"; the dashboard showed nothing).
+        Said once per reason, with where to look."""
+        try:
+            body = response.json()
+        except Exception:  # noqa: BLE001 - a non-JSON 200 is a stored batch as far as we know
+            return
+        if not isinstance(body, dict) or body.get("status") != "discarded":
+            return
+        reason = str(body.get("reason") or "unspecified")
+        if reason in self._warned_discard_reasons:
+            return
+        self._warned_discard_reasons.add(reason)
+        # The ingest's IP-exclusion reasons are user_excluded_ip and auto_excluded_login_ip
+        # (datacenter_ip exists but never fires for backend events); anything else gets the
+        # generic pointer rather than a guess.
+        if reason.endswith("_ip"):
+            where = (
+                "Events from this machine's IP are excluded for this project — see Setup → "
+                "Security for this project in the Scope dashboard ('Your own traffic' and "
+                "'Exclusions') and remove the exclusion to see them."
+            )
+        else:
+            where = "Check the project's settings in the Scope dashboard."
+        self.config.warn(
+            f"Scope received {count} event(s) but DISCARDED them (reason: {reason}). {where} "
+            f"This is said once per reason."
+        )
+
+    def test_connection(self) -> bool:
+        """
+        Test connection to API
+
+        Returns:
+            True if connection successful, False otherwise
+        """
+        try:
+            self.config.log("Testing API connection...")
+
+            # Same reason as ship_events: Scope's own traffic is never captured.
+            with ScopeContext.scope_internal():
+                # Simple health check (could be a ping endpoint)
+                # For now, just verify we can reach the endpoint
+                response = self.client.get(f"{self.config.endpoint}/health")
+
+            if response.status_code == 200:
+                self.config.log("✅ API connection successful")
+                return True
+            else:
+                self.config.log(f"⚠️ API returned status {response.status_code}")
+                return False
+
+        except Exception as e:
+            self.config.log(f"⚠️ Could not connect to API: {e}")
+            return False
+
+    def close(self):
+        """Close HTTP client"""
+        self.client.close()
+        self.config.log("API client closed")

{scope_analytics-0.1.4 → scope_analytics-0.1.5}/scope_analytics/config.py

@@ -149,7 +149,11 @@ class ScopeConfig:
     def log(self, message: str):
         """Log debug message if debug mode enabled"""
         if self.debug:
-            print(f"[Scope SDK] {message}")
+            # flush: under gunicorn, in a container, or anywhere stdout is a pipe or a
+            # file, Python buffers prints — and a worker that exits through os._exit()
+            # never writes the buffer out, so SCOPE_DEBUG=true showed nothing from any
+            # worker (the master's lines appeared; the "Captured …" lines never did).
+            print(f"[Scope SDK] {message}", flush=True)
 
     def warn(self, message: str):
         """Always-visible warning. Deliberately NOT gated on ``debug``.

{scope_analytics-0.1.4 → scope_analytics-0.1.5}/scope_analytics/context.py

@@ -202,6 +202,12 @@ class ScopeContext:
             ScopeContext._background_session_id = f"temp_bg_{uuid.uuid4().hex[:12]}"
         return ScopeContext._background_session_id
 
+    @staticmethod
+    def reset_background_session() -> None:
+        """Forget this process's background session id. Called in a forked child, which
+        is a new process and must not share its parent's id."""
+        ScopeContext._background_session_id = None
+
     @staticmethod
     def generate_temp_session_id() -> str:
         """