apifyhub-sentinel 0.3.0__tar.gz

apifyhub_sentinel-0.3.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/

apifyhub_sentinel-0.3.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: apifyhub-sentinel
+Version: 0.3.0
+Summary: Drop-in error tracking for Apify actors. One wrapper: with sentinel(apify_hub_key=...).
+Project-URL: Homepage, https://apifyhub.com
+Project-URL: Documentation, https://apifyhub.com/features/sentinel
+Author: apifyhub
+License: MIT
+Keywords: actor,apify,error-tracking,monitoring,sentinel
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# apifyhub-sentinel
+
+Drop-in **error tracking** for [Apify](https://apify.com) actors — the Python
+port of [`@apifyhub/sentinel`](../js). It captures exceptions, **groups them
+into issues** by fingerprint, carries breadcrumbs, the run's input and the full
+Apify run context (run/actor/build ids, consumer, origin), and reports each to
+your apifyHub dashboard.
+
+Both ports ship as one product under **one version number** and produce
+identical fingerprints, so the same bug raised from a JS actor and a Python
+actor lands in the same issue.
+
+## Install
+
+```bash
+pip install apifyhub-sentinel
+```
+
+Requires Python 3.9+. Zero runtime dependencies (stdlib `urllib` only).
+
+## Usage
+
+Wrap your actor body — any raise is captured, grouped, flushed, and re-raised
+unchanged:
+
+```python
+import os
+from apifyhub_sentinel import sentinel
+
+with sentinel(apify_hub_key=os.environ["APIFYHUB_KEY"]):
+    ...  # the actor's normal code
+```
+
+Or wire it manually for finer control:
+
+```python
+from apifyhub_sentinel import init, capture_exception, add_breadcrumb, flush
+
+init(apify_hub_key=os.environ["APIFYHUB_KEY"])
+
+add_breadcrumb(category="http", message="GET /search", level="info")
+
+try:
+    do_work()
+except Exception as exc:
+    capture_exception(exc)   # grouped into an issue by fingerprint
+    flush()                  # ensure delivery before the container exits
+    raise
+```
+
+### Setup
+
+1. Generate an **apifyHub key** on your [apifyhub.com](https://apifyhub.com) profile.
+2. Add it as a **secret env var** named `APIFYHUB_KEY` (Apify Console → your actor →
+   Settings → Environment variables).
+3. Deploy. Crashes and captured errors now show up as issues on your dashboard.
+
+## API
+
+| Function | Purpose |
+| --- | --- |
+| `init(apify_hub_key, **opts)` | Initialise; installs global excepthooks (unless `capture_unhandled=False`). Idempotent. |
+| `sentinel(apify_hub_key, **opts)` | Context manager: init + capture/flush/re-raise around the body. |
+| `capture_exception(exc, ...)` | Report an exception. Returns the event id. |
+| `capture_message(msg, ...)` | Report a plain message at a given `level`. |
+| `add_breadcrumb(...)` | Append a timeline entry shown with the next error. |
+| `set_tag(k, v)` / `set_context(name, obj)` / `set_user(...)` | Attach metadata to subsequent events. |
+| `flush(timeout_s=2.0)` | Await in-flight sends. Returns whether it drained in time. |
+
+### Options
+
+Every option `init()` takes is also accepted by `sentinel()`:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `apify_hub_key` | required | Bearer token; the server SHA-256 hashes it and matches the owner's hash. |
+| `endpoint` | production | Override the ingest URL. |
+| `debug` | `False` | Print internal failures to stderr. |
+| `force_outside_apify` | `False` | Send even when `APIFY_IS_AT_HOME != "1"` (local testing). |
+| `capture_unhandled` | `True` | Install `sys.excepthook` / `threading.excepthook` handlers. |
+| `capture_input` | `True` | Fetch the run's INPUT record and attach it as `contexts.input`. |
+| `sample_rate` | `1.0` | Drop a fraction of events client-side. |
+| `max_breadcrumbs` | `50` | Ring-buffer size per scope. |
+| `release` / `environment` | `None` | Free-form labels carried on every event. |
+| `before_send` | `None` | Last-chance hook to scrub or drop an event (return `None` to drop). |
+
+## Input capture
+
+The run's `INPUT` record is fetched once at init on a background thread and
+attached to every event as `contexts.input`, so you can see what the actor was
+asked to do when it broke. Notes:
+
+- **Secret input fields stay encrypted.** Only the Apify SDK's `get_input()`
+  decrypts them, so no plaintext secrets reach the dashboard.
+- Oversized inputs (>16KB) are truncated.
+- Best-effort: a crash before the fetch resolves ships without input.
+- Turn it off with `capture_input=False`.
+
+## Differences from the JS port
+
+Behaviour is deliberately identical; only the idioms differ.
+
+- `with sentinel(...)` replaces `await withSentinel(options, fn)`.
+- Options are snake_case keyword arguments rather than an options object.
+- `flush()` is synchronous and returns `bool` (no `await`).
+- Uncaught errors are caught via `sys.excepthook` and `threading.excepthook`.
+  Both chain to the previous hook, so the traceback still prints and the process
+  still exits non-zero — matching the JS port, which restores Node's default
+  crash semantics by hand.
+- Stack frames come from `traceback.extract_tb`, which is already newest-last,
+  so unlike the JS port there is no reversal step.
+
+## Tests
+
+```bash
+./run_tests.sh
+```
+
+Runs the unit tests, then the **cross-port parity check**: `tests/check_parity.mjs`
+computes fingerprints with the JS source and `tests/compare_parity.py` asserts
+the Python port produces the same 8-char hex for every case. That check is the
+thing that keeps one bug from splitting into two issues on the dashboard, so run
+it after touching `_fingerprint.py` or the JS `fingerprint.ts`.

apifyhub_sentinel-0.3.0/README.md

@@ -0,0 +1,123 @@
+# apifyhub-sentinel
+
+Drop-in **error tracking** for [Apify](https://apify.com) actors — the Python
+port of [`@apifyhub/sentinel`](../js). It captures exceptions, **groups them
+into issues** by fingerprint, carries breadcrumbs, the run's input and the full
+Apify run context (run/actor/build ids, consumer, origin), and reports each to
+your apifyHub dashboard.
+
+Both ports ship as one product under **one version number** and produce
+identical fingerprints, so the same bug raised from a JS actor and a Python
+actor lands in the same issue.
+
+## Install
+
+```bash
+pip install apifyhub-sentinel
+```
+
+Requires Python 3.9+. Zero runtime dependencies (stdlib `urllib` only).
+
+## Usage
+
+Wrap your actor body — any raise is captured, grouped, flushed, and re-raised
+unchanged:
+
+```python
+import os
+from apifyhub_sentinel import sentinel
+
+with sentinel(apify_hub_key=os.environ["APIFYHUB_KEY"]):
+    ...  # the actor's normal code
+```
+
+Or wire it manually for finer control:
+
+```python
+from apifyhub_sentinel import init, capture_exception, add_breadcrumb, flush
+
+init(apify_hub_key=os.environ["APIFYHUB_KEY"])
+
+add_breadcrumb(category="http", message="GET /search", level="info")
+
+try:
+    do_work()
+except Exception as exc:
+    capture_exception(exc)   # grouped into an issue by fingerprint
+    flush()                  # ensure delivery before the container exits
+    raise
+```
+
+### Setup
+
+1. Generate an **apifyHub key** on your [apifyhub.com](https://apifyhub.com) profile.
+2. Add it as a **secret env var** named `APIFYHUB_KEY` (Apify Console → your actor →
+   Settings → Environment variables).
+3. Deploy. Crashes and captured errors now show up as issues on your dashboard.
+
+## API
+
+| Function | Purpose |
+| --- | --- |
+| `init(apify_hub_key, **opts)` | Initialise; installs global excepthooks (unless `capture_unhandled=False`). Idempotent. |
+| `sentinel(apify_hub_key, **opts)` | Context manager: init + capture/flush/re-raise around the body. |
+| `capture_exception(exc, ...)` | Report an exception. Returns the event id. |
+| `capture_message(msg, ...)` | Report a plain message at a given `level`. |
+| `add_breadcrumb(...)` | Append a timeline entry shown with the next error. |
+| `set_tag(k, v)` / `set_context(name, obj)` / `set_user(...)` | Attach metadata to subsequent events. |
+| `flush(timeout_s=2.0)` | Await in-flight sends. Returns whether it drained in time. |
+
+### Options
+
+Every option `init()` takes is also accepted by `sentinel()`:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `apify_hub_key` | required | Bearer token; the server SHA-256 hashes it and matches the owner's hash. |
+| `endpoint` | production | Override the ingest URL. |
+| `debug` | `False` | Print internal failures to stderr. |
+| `force_outside_apify` | `False` | Send even when `APIFY_IS_AT_HOME != "1"` (local testing). |
+| `capture_unhandled` | `True` | Install `sys.excepthook` / `threading.excepthook` handlers. |
+| `capture_input` | `True` | Fetch the run's INPUT record and attach it as `contexts.input`. |
+| `sample_rate` | `1.0` | Drop a fraction of events client-side. |
+| `max_breadcrumbs` | `50` | Ring-buffer size per scope. |
+| `release` / `environment` | `None` | Free-form labels carried on every event. |
+| `before_send` | `None` | Last-chance hook to scrub or drop an event (return `None` to drop). |
+
+## Input capture
+
+The run's `INPUT` record is fetched once at init on a background thread and
+attached to every event as `contexts.input`, so you can see what the actor was
+asked to do when it broke. Notes:
+
+- **Secret input fields stay encrypted.** Only the Apify SDK's `get_input()`
+  decrypts them, so no plaintext secrets reach the dashboard.
+- Oversized inputs (>16KB) are truncated.
+- Best-effort: a crash before the fetch resolves ships without input.
+- Turn it off with `capture_input=False`.
+
+## Differences from the JS port
+
+Behaviour is deliberately identical; only the idioms differ.
+
+- `with sentinel(...)` replaces `await withSentinel(options, fn)`.
+- Options are snake_case keyword arguments rather than an options object.
+- `flush()` is synchronous and returns `bool` (no `await`).
+- Uncaught errors are caught via `sys.excepthook` and `threading.excepthook`.
+  Both chain to the previous hook, so the traceback still prints and the process
+  still exits non-zero — matching the JS port, which restores Node's default
+  crash semantics by hand.
+- Stack frames come from `traceback.extract_tb`, which is already newest-last,
+  so unlike the JS port there is no reversal step.
+
+## Tests
+
+```bash
+./run_tests.sh
+```
+
+Runs the unit tests, then the **cross-port parity check**: `tests/check_parity.mjs`
+computes fingerprints with the JS source and `tests/compare_parity.py` asserts
+the Python port produces the same 8-char hex for every case. That check is the
+thing that keeps one bug from splitting into two issues on the dashboard, so run
+it after touching `_fingerprint.py` or the JS `fingerprint.ts`.

apifyhub_sentinel-0.3.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apifyhub-sentinel"
+# Kept in lockstep with @apifyhub/sentinel: the two ports ship as one product.
+version = "0.3.0"
+description = "Drop-in error tracking for Apify actors. One wrapper: with sentinel(apify_hub_key=...)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "apifyhub" }]
+dependencies = []
+keywords = ["apify", "error-tracking", "monitoring", "actor", "sentinel"]
+
+[project.urls]
+Homepage = "https://apifyhub.com"
+Documentation = "https://apifyhub.com/features/sentinel"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apifyhub_sentinel"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/apifyhub_sentinel", "README.md"]

apifyhub_sentinel-0.3.0/src/apifyhub_sentinel/__init__.py

@@ -0,0 +1,470 @@
+"""apifyhub-sentinel — drop-in error tracking for Apify actors.
+
+The Python port of `@apifyhub/sentinel`. Same wire format, same grouping, same
+dashboard:
+
+    from apifyhub_sentinel import sentinel
+
+    with sentinel(apify_hub_key=os.environ["APIFYHUB_KEY"]):
+        ...  # the actor's normal code. Any raise is captured, grouped,
+             # flushed, and re-raised unchanged.
+
+Or wire it manually:
+
+    from apifyhub_sentinel import init, capture_exception, add_breadcrumb, flush
+
+    init(apify_hub_key=os.environ["APIFYHUB_KEY"])
+    try:
+        do_work()
+    except Exception as exc:
+        capture_exception(exc)   # grouped into an issue by fingerprint
+        flush()                  # ensure delivery before the container exits
+        raise
+
+Hard rules (shared with @apifyhub/analytics and the JS sentinel SDK):
+  1. Never raise. A bad key, network outage, or non-Apify environment must
+     never crash the host actor or swallow its error.
+  2. The key travels as `Authorization: Bearer`, never in the body.
+  3. Idempotent init; calling it twice in a process is a no-op after the first.
+  4. Zero runtime deps. Uses urllib from the stdlib.
+"""
+from __future__ import annotations
+
+import sys
+import threading
+import time
+import uuid
+from contextlib import contextmanager
+from typing import Any, Callable, Dict, Iterator, List, Optional
+
+from ._env import EnvSnapshot, read_env
+from ._fingerprint import compute_fingerprint, parse_stack
+from ._input import fetch_actor_input
+from ._source import attach_source_context
+from ._transport import flush as _transport_flush
+from ._transport import send_event
+
+__all__ = [
+    "sentinel",
+    "init",
+    "capture_exception",
+    "capture_message",
+    "add_breadcrumb",
+    "set_tag",
+    "set_context",
+    "set_user",
+    "flush",
+    "VERSION",
+]
+
+# Kept in lockstep with sdk/sentinel/js/src/index.ts — the two ports ship as
+# one product and are documented with a single version number.
+VERSION = "0.3.0"
+
+_DEFAULT_ENDPOINT = "https://notable-toad-601.convex.site/v1/sentinel-ingest"
+
+_SEVERITIES = ("fatal", "error", "warning", "info", "debug")
+
+
+class _Scope:
+    """Mutable per-process scope: tags/contexts/user/breadcrumbs on events."""
+
+    def __init__(self) -> None:
+        self.tags: Dict[str, str] = {}
+        self.contexts: Dict[str, Dict[str, Any]] = {}
+        self.user: Optional[Dict[str, Any]] = None
+        self.breadcrumbs: List[Dict[str, Any]] = []
+        self.lock = threading.Lock()
+
+
+class _Client:
+    def __init__(
+        self, options: Dict[str, Any], endpoint: str, env: EnvSnapshot
+    ) -> None:
+        self.options = options
+        self.endpoint = endpoint
+        self.env = env
+        self.scope = _Scope()
+
+
+# Module-level singleton, mirroring the JS port's implicit global hub.
+_client: Optional[_Client] = None
+_client_lock = threading.Lock()
+
+
+def _current() -> Optional[_Client]:
+    return _client
+
+
+def init(
+    apify_hub_key: str,
+    *,
+    endpoint: Optional[str] = None,
+    debug: bool = False,
+    force_outside_apify: bool = False,
+    capture_unhandled: bool = True,
+    capture_input: bool = True,
+    sample_rate: float = 1.0,
+    max_breadcrumbs: int = 50,
+    release: Optional[str] = None,
+    environment: Optional[str] = None,
+    before_send: Optional[Callable[[Dict[str, Any]], Optional[Dict[str, Any]]]] = None,
+) -> None:
+    """Initialise the SDK.
+
+    Safe to call anywhere; returns silently (no-op) on a missing key, outside
+    Apify, or on a second call. Installs global excepthooks unless
+    `capture_unhandled=False`.
+    """
+    global _client
+    try:
+        if not apify_hub_key or not isinstance(apify_hub_key, str):
+            if debug:
+                print("[sentinel] missing apify_hub_key — no-op", file=sys.stderr)
+            return
+        env = read_env()
+        if not env.is_at_home and not force_outside_apify:
+            if debug:
+                print(
+                    "[sentinel] APIFY_IS_AT_HOME!=1 — no-op "
+                    "(pass force_outside_apify to override)",
+                    file=sys.stderr,
+                )
+            return
+
+        with _client_lock:
+            if _client is not None:
+                if debug:
+                    print("[sentinel] already initialised — skipping", file=sys.stderr)
+                return
+            options: Dict[str, Any] = {
+                "apify_hub_key": apify_hub_key,
+                "debug": debug,
+                "sample_rate": sample_rate,
+                "max_breadcrumbs": max_breadcrumbs,
+                "release": release,
+                "environment": environment,
+                "before_send": before_send,
+            }
+            client = _Client(options, endpoint or _DEFAULT_ENDPOINT, env)
+            if env.user_id:
+                client.scope.user = {
+                    "id": env.user_id,
+                    "isPaying": env.user_is_paying,
+                }
+            _client = client
+
+        if capture_unhandled:
+            _install_global_handlers(client)
+
+        if capture_input:
+
+            def _on_input(payload: Dict[str, Any]) -> None:
+                # Don't clobber an input the caller already set via set_context.
+                with client.scope.lock:
+                    if "input" not in client.scope.contexts:
+                        client.scope.contexts["input"] = payload
+
+            fetch_actor_input(env, _on_input)
+
+        if debug:
+            print(
+                f"[sentinel] initialised run={env.run_id} "
+                f"actor={env.actor_full_name or env.actor_id}",
+                file=sys.stderr,
+            )
+    except Exception:
+        # A bug in init() must never crash the host actor.
+        pass
+
+
+def set_tag(key: str, value: str) -> None:
+    """Attach a key/value tag to every subsequent event."""
+    try:
+        c = _current()
+        if c and isinstance(key, str):
+            with c.scope.lock:
+                c.scope.tags[key] = str(value)
+    except Exception:
+        pass
+
+
+def set_context(name: str, ctx: Dict[str, Any]) -> None:
+    """Attach a named context block (e.g. "input", "proxy") to later events."""
+    try:
+        c = _current()
+        if c and isinstance(name, str):
+            with c.scope.lock:
+                c.scope.contexts[name] = ctx
+    except Exception:
+        pass
+
+
+def set_user(
+    *, id: Optional[str] = None, is_paying: Optional[bool] = None
+) -> None:
+    """Identify the consumer. Defaults to the Apify user id when available."""
+    try:
+        c = _current()
+        if c:
+            with c.scope.lock:
+                c.scope.user = {"id": id, "isPaying": is_paying}
+    except Exception:
+        pass
+
+
+def add_breadcrumb(
+    *,
+    message: Optional[str] = None,
+    category: Optional[str] = None,
+    level: Optional[str] = None,
+    data: Optional[Dict[str, Any]] = None,
+    timestamp: Optional[int] = None,
+) -> None:
+    """Record a timeline entry shown alongside the error that follows.
+
+    Oldest are dropped past `max_breadcrumbs` (default 50). No-op before init.
+    """
+    try:
+        c = _current()
+        if not c:
+            return
+        crumb: Dict[str, Any] = {"timestamp": timestamp or _now_ms()}
+        if category is not None:
+            crumb["category"] = category
+        if message is not None:
+            crumb["message"] = message
+        if level is not None:
+            crumb["level"] = level
+        if data is not None:
+            crumb["data"] = data
+        max_crumbs = c.options.get("max_breadcrumbs") or 50
+        with c.scope.lock:
+            c.scope.breadcrumbs.append(crumb)
+            if len(c.scope.breadcrumbs) > max_crumbs:
+                del c.scope.breadcrumbs[: len(c.scope.breadcrumbs) - max_crumbs]
+    except Exception:
+        pass
+
+
+def capture_exception(
+    error: BaseException,
+    *,
+    level: str = "error",
+    handled: bool = True,
+    tags: Optional[Dict[str, str]] = None,
+) -> Optional[str]:
+    """Report an exception. Returns the event id, or None if dropped."""
+    try:
+        c = _current()
+        if not c:
+            return None
+        exc_type = type(error).__name__ if error is not None else "Error"
+        message = str(error) if error is not None else ""
+        frames = parse_stack(getattr(error, "__traceback__", None))
+        attach_source_context(frames)
+        event = _base_event(c, _severity(level), handled)
+        event["exception"] = {
+            "type": exc_type,
+            "value": message,
+            "stacktrace": frames,
+        }
+        event["fingerprint"] = compute_fingerprint(exc_type, message, frames)
+        if tags:
+            event["tags"] = {**event["tags"], **tags}
+        return _dispatch(c, event)
+    except Exception:
+        return None
+
+
+def capture_message(
+    message: str,
+    *,
+    level: str = "info",
+    tags: Optional[Dict[str, str]] = None,
+) -> Optional[str]:
+    """Report a plain message. Grouped by normalized text."""
+    try:
+        c = _current()
+        if not c:
+            return None
+        event = _base_event(c, _severity(level), True)
+        event["message"] = message
+        event["fingerprint"] = compute_fingerprint("Message", message, [])
+        if tags:
+            event["tags"] = {**event["tags"], **tags}
+        return _dispatch(c, event)
+    except Exception:
+        return None
+
+
+def flush(timeout_s: float = 2.0) -> bool:
+    """Await in-flight sends. True if everything drained in time."""
+    return _transport_flush(timeout_s)
+
+
+@contextmanager
+def sentinel(apify_hub_key: str, **kwargs: Any) -> Iterator[None]:
+    """Wrap the actor body so any raise is captured, flushed and re-raised.
+
+    Accepts every keyword `init()` does. A hard kill (OOM/timeout/abort)
+    bypasses the handler, so those crashes are only caught when the global
+    excepthooks were installed (the default).
+    """
+    init(apify_hub_key, **kwargs)
+    try:
+        yield
+    except BaseException as exc:  # noqa: BLE001 - re-raised untouched below
+        try:
+            capture_exception(exc, level="fatal", handled=False)
+            flush()
+        except Exception:
+            # Reporting must never change the actor's outcome.
+            pass
+        raise
+    else:
+        # Flush on the clean path too: any handled capture_exception still in
+        # flight would be lost when the container exits.
+        try:
+            flush()
+        except Exception:
+            pass
+
+
+# ---- internals ------------------------------------------------------------
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _severity(level: Optional[str]) -> str:
+    return level if level in _SEVERITIES else "error"
+
+
+def _base_event(c: _Client, level: str, handled: bool) -> Dict[str, Any]:
+    env = c.env
+    with c.scope.lock:
+        # Snapshot so later additions don't mutate a queued event.
+        breadcrumbs = list(c.scope.breadcrumbs)
+        tags = dict(c.scope.tags)
+        contexts = dict(c.scope.contexts)
+        user = dict(c.scope.user) if c.scope.user else None
+    event: Dict[str, Any] = {
+        "eventType": "SENTINEL.ERROR",
+        "apifyHubSdkLanguage": "python",
+        "apifyHubSdkVersion": VERSION,
+        "eventId": _event_id(),
+        "timestamp": _now_ms(),
+        "level": level,
+        "fingerprint": "",
+        "handled": handled,
+        "breadcrumbs": breadcrumbs,
+        "tags": tags,
+        "contexts": contexts,
+    }
+    if user:
+        event["user"] = user
+    for key, value in (
+        ("release", c.options.get("release")),
+        ("environment", c.options.get("environment")),
+        ("runId", env.run_id),
+        ("actorId", env.actor_id),
+        ("actorFullName", env.actor_full_name),
+        ("buildId", env.build_id),
+        ("buildNumber", env.build_number),
+        ("taskId", env.task_id),
+        ("origin", env.origin),
+    ):
+        if value is not None:
+            event[key] = value
+    return event
+
+
+def _dispatch(c: _Client, event: Dict[str, Any]) -> Optional[str]:
+    """Apply sampling + before_send, then hand to the transport."""
+    configured = c.options.get("sample_rate", 1.0)
+    try:
+        rate = float(configured)
+        if rate != rate:  # NaN
+            rate = 1.0
+    except (TypeError, ValueError):
+        rate = 1.0
+    rate = max(0.0, min(1.0, rate))
+    if rate < 1.0 and _hash_unit(event["eventId"]) >= rate:
+        return None
+
+    out: Optional[Dict[str, Any]] = event
+    before_send = c.options.get("before_send")
+    if before_send:
+        try:
+            out = before_send(event)
+        except Exception:
+            out = event  # a raising hook must not drop the event
+    if not out:
+        return None
+
+    send_event(
+        c.endpoint, c.options["apify_hub_key"], out, bool(c.options.get("debug"))
+    )
+    return out.get("eventId")
+
+
+def _install_global_handlers(c: _Client) -> None:
+    """Report uncaught exceptions, then defer to the previous hook.
+
+    Chaining to the previous hook (rather than replacing it) preserves the
+    interpreter's default behaviour: the traceback still prints and the process
+    still exits non-zero, which is what the JS port goes out of its way to
+    restore.
+    """
+    try:
+        previous_hook = sys.excepthook
+
+        def hook(exc_type, exc_value, exc_tb):  # type: ignore[no-untyped-def]
+            try:
+                if exc_value is not None:
+                    capture_exception(exc_value, level="fatal", handled=False)
+                    flush()
+            except Exception:
+                pass  # never mask the original crash with our own
+            previous_hook(exc_type, exc_value, exc_tb)
+
+        sys.excepthook = hook
+
+        # Uncaught exceptions on non-main threads go through a separate hook.
+        previous_thread_hook = getattr(threading, "excepthook", None)
+        if previous_thread_hook is not None:
+
+            def thread_hook(args):  # type: ignore[no-untyped-def]
+                try:
+                    if args.exc_value is not None:
+                        capture_exception(
+                            args.exc_value, level="fatal", handled=False
+                        )
+                        flush()
+                except Exception:
+                    pass
+                previous_thread_hook(args)
+
+            threading.excepthook = thread_hook
+
+        if c.options.get("debug"):
+            print("[sentinel] global handlers installed", file=sys.stderr)
+    except Exception:
+        pass
+
+
+def _event_id() -> str:
+    try:
+        return uuid.uuid4().hex
+    except Exception:
+        return format(_now_ms(), "x").rjust(16, "0")
+
+
+def _hash_unit(event_id: str) -> float:
+    """Map an id to a stable [0,1) for deterministic sampling."""
+    h = 0
+    for ch in event_id:
+        h = (h * 31 + ord(ch)) & 0xFFFFFFFF
+    return h / 0xFFFFFFFF

apifyhub_sentinel-0.3.0/src/apifyhub_sentinel/_env.py

@@ -0,0 +1,68 @@
+"""Apify run-context snapshot.
+
+Mirrors `sdk/sentinel/js/src/env.ts` field for field so both SDKs put the same
+run context on the wire. Kept as its own copy (rather than importing from the
+analytics package) so this package stays zero-dependency and the two SDKs can
+version independently.
+"""
+from __future__ import annotations
+
+import os
+from typing import Dict, NamedTuple, Optional
+
+
+class EnvSnapshot(NamedTuple):
+    is_at_home: bool
+    run_id: Optional[str] = None
+    actor_id: Optional[str] = None
+    actor_full_name: Optional[str] = None
+    build_id: Optional[str] = None
+    build_number: Optional[str] = None
+    task_id: Optional[str] = None
+    user_id: Optional[str] = None
+    user_is_paying: Optional[bool] = None
+    started_at: Optional[str] = None
+    origin: Optional[str] = None
+    # For fetching the run's INPUT record (input capture).
+    default_key_value_store_id: Optional[str] = None
+    input_key: Optional[str] = None
+    token: Optional[str] = None
+    api_base_url: Optional[str] = None
+
+
+def _first(e: Dict[str, str], *names: str) -> Optional[str]:
+    """First non-empty value among `names`, matching the JS `??` chains."""
+    for n in names:
+        v = e.get(n)
+        if v:
+            return v
+    return None
+
+
+def _parse_bool(v: Optional[str]) -> Optional[bool]:
+    if v is None or v == "":
+        return None
+    return v == "1" or v.lower() == "true"
+
+
+def read_env() -> EnvSnapshot:
+    e = dict(os.environ)
+    return EnvSnapshot(
+        is_at_home=e.get("APIFY_IS_AT_HOME") == "1",
+        run_id=_first(e, "ACTOR_RUN_ID", "APIFY_ACTOR_RUN_ID"),
+        actor_id=_first(e, "ACTOR_ID", "APIFY_ACTOR_ID"),
+        actor_full_name=_first(e, "ACTOR_FULL_NAME"),
+        build_id=_first(e, "ACTOR_BUILD_ID", "APIFY_ACTOR_BUILD_ID"),
+        build_number=_first(e, "ACTOR_BUILD_NUMBER"),
+        task_id=_first(e, "ACTOR_TASK_ID", "APIFY_ACTOR_TASK_ID"),
+        user_id=_first(e, "APIFY_USER_ID"),
+        user_is_paying=_parse_bool(e.get("APIFY_USER_IS_PAYING")),
+        started_at=_first(e, "ACTOR_STARTED_AT", "APIFY_STARTED_AT"),
+        origin=_first(e, "APIFY_META_ORIGIN"),
+        default_key_value_store_id=_first(
+            e, "ACTOR_DEFAULT_KEY_VALUE_STORE_ID", "APIFY_DEFAULT_KEY_VALUE_STORE_ID"
+        ),
+        input_key=_first(e, "ACTOR_INPUT_KEY", "APIFY_INPUT_KEY"),
+        token=_first(e, "APIFY_TOKEN"),
+        api_base_url=_first(e, "APIFY_API_PUBLIC_BASE_URL"),
+    )

apifyhub_sentinel-0.3.0/src/apifyhub_sentinel/_fingerprint.py

@@ -0,0 +1,132 @@
+"""Error grouping, ported from `sdk/sentinel/js/src/fingerprint.ts`.
+
+The hash algorithm and the string fed into it must stay byte-identical to the
+JS SDK: the server buckets events into issues purely by this key, so a drift
+between the two ports would split one bug into two issues.
+
+Exceptions with a stack hash as: exception type + the in-app frame chain
+(filename:function), message excluded, like Sentry. Stackless events
+(capture_message) hash the normalized message instead, with volatile tokens
+replaced by placeholders so "Timeout after 314ms" and "Timeout after 2200ms"
+share a bucket.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sysconfig
+import traceback
+from types import TracebackType
+from typing import Any, Dict, List, Optional
+
+# Frames from these trees are not "in app" — the equivalent of the JS port's
+# node_modules / node: checks.
+_VENDOR_MARKERS = (
+    os.sep + "site-packages" + os.sep,
+    os.sep + "dist-packages" + os.sep,
+    os.sep + "lib-dynload" + os.sep,
+)
+
+
+def _stdlib_dirs() -> List[str]:
+    dirs = []
+    for key in ("stdlib", "platstdlib"):
+        try:
+            p = sysconfig.get_paths().get(key)
+        except Exception:
+            p = None
+        if p:
+            dirs.append(os.path.normpath(p) + os.sep)
+    return dirs
+
+
+_STDLIB_DIRS = _stdlib_dirs()
+
+
+def is_in_app(filename: Optional[str]) -> bool:
+    if not filename:
+        return False
+    norm = os.path.normpath(filename)
+    if any(m in norm for m in _VENDOR_MARKERS):
+        return False
+    # A stdlib path is only vendor code if it is not also site-packages, which
+    # the check above already excluded.
+    if any(norm.startswith(d) for d in _STDLIB_DIRS):
+        return False
+    return True
+
+
+def parse_stack(tb: Optional[TracebackType]) -> List[Dict[str, Any]]:
+    """Traceback -> Sentry-shaped frames, newest LAST.
+
+    `traceback.extract_tb` already yields outermost-first / innermost-last,
+    which is the order the dashboard expects, so unlike the JS port (which
+    reverses V8's newest-first stack) there is nothing to flip here.
+    """
+    frames: List[Dict[str, Any]] = []
+    if tb is None:
+        return frames
+    try:
+        for fs in traceback.extract_tb(tb):
+            frames.append(
+                {
+                    "function": fs.name or None,
+                    "filename": fs.filename,
+                    "lineno": fs.lineno,
+                    "in_app": is_in_app(fs.filename),
+                }
+            )
+    except Exception:
+        return frames
+    return frames
+
+
+_UUID_RE = re.compile(
+    r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b", re.I
+)
+_URL_RE = re.compile(r"\bhttps?://\S+", re.I)
+_HEX_RE = re.compile(r"\b0x[0-9a-f]+\b", re.I)
+# No word boundaries: a number glued to a unit ("314ms") must still normalize.
+_NUM_RE = re.compile(r"\d[\d.,]*")
+_STR_RE = re.compile(r"(['\"]).*?\1")
+_WS_RE = re.compile(r"\s+")
+
+
+def normalize_message(msg: str) -> str:
+    """Replace run-to-run-volatile tokens so similar messages group together."""
+    out = _UUID_RE.sub("<uuid>", msg)
+    out = _URL_RE.sub("<url>", out)
+    out = _HEX_RE.sub("<hex>", out)
+    out = _NUM_RE.sub("<num>", out)
+    out = _STR_RE.sub("<str>", out)
+    out = _WS_RE.sub(" ", out)
+    return out.strip()
+
+
+def fnv1a(text: str) -> str:
+    """FNV-1a 32-bit -> 8-char hex.
+
+    The JS port hashes UTF-16 code units (`charCodeAt`), so this iterates the
+    same units rather than bytes or code points: for any string containing
+    astral characters, hashing code points would diverge from JS.
+    """
+    h = 0x811C9DC5
+    data = text.encode("utf-16-le")
+    for i in range(0, len(data), 2):
+        code_unit = data[i] | (data[i + 1] << 8)
+        h ^= code_unit
+        h = (h * 0x01000193) & 0xFFFFFFFF
+    return format(h, "08x")
+
+
+def compute_fingerprint(
+    exc_type: str, message: str, frames: List[Dict[str, Any]]
+) -> str:
+    in_app = [f for f in frames if f.get("in_app")]
+    chosen = in_app if in_app else frames[-1:]
+    chain = "\n".join(
+        f"{f.get('filename')}:{f.get('function') or '?'}" for f in chosen
+    )
+    if not chain:
+        return fnv1a(f"{exc_type}\n{normalize_message(message)}")
+    return fnv1a(f"{exc_type}\n{chain}")

apifyhub_sentinel-0.3.0/src/apifyhub_sentinel/_input.py

@@ -0,0 +1,75 @@
+"""Actor input capture, ported from `sdk/sentinel/js/src/input.ts`.
+
+The run's INPUT record lives in its default key-value store, always readable
+from inside the container with the run's own token, so we fetch it once at init
+on a background thread and attach it to the scope as `contexts.input`, where
+every subsequent event picks it up.
+
+Notes:
+  - Best-effort: an error before the fetch resolves ships without input.
+  - Secret input fields arrive still encrypted (only the Apify SDK's get_input()
+    decrypts them), so no plaintext secrets reach the dashboard.
+  - Payload-capped: oversized inputs are stored as a truncated string.
+  - Never raises, same as the rest of the SDK.
+"""
+from __future__ import annotations
+
+import json
+import threading
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict
+
+from ._env import EnvSnapshot
+
+MAX_INPUT_CHARS = 16_384
+FETCH_TIMEOUT_S = 5.0
+
+
+def fetch_actor_input(
+    env: EnvSnapshot, on_ready: Callable[[Dict[str, Any]], None]
+) -> None:
+    """Kick off a background fetch of the run's INPUT record."""
+    try:
+        if not env.default_key_value_store_id or not env.token:
+            return
+        t = threading.Thread(target=_fetch, args=(env, on_ready), daemon=True)
+        t.start()
+    except Exception:
+        # Never crash the host actor.
+        pass
+
+
+def _fetch(env: EnvSnapshot, on_ready: Callable[[Dict[str, Any]], None]) -> None:
+    try:
+        base = env.api_base_url or "https://api.apify.com"
+        key = env.input_key or "INPUT"
+        url = (
+            f"{base}/v2/key-value-stores/{env.default_key_value_store_id}"
+            f"/records/{urllib.parse.quote(key, safe='')}"
+        )
+        req = urllib.request.Request(
+            url, headers={"Authorization": f"Bearer {env.token}"}
+        )
+        with urllib.request.urlopen(req, timeout=FETCH_TIMEOUT_S) as res:
+            if not (200 <= res.status < 300):
+                return
+            raw = res.read()
+        if not raw:
+            return
+        text = raw.decode("utf-8", errors="replace")
+        if len(text) > MAX_INPUT_CHARS:
+            on_ready({"truncated": True, "raw": text[:MAX_INPUT_CHARS]})
+            return
+        try:
+            parsed = json.loads(text)
+        except Exception:
+            on_ready({"raw": text})  # non-JSON input (e.g. plain text record)
+            return
+        if isinstance(parsed, dict):
+            on_ready(parsed)
+        else:
+            on_ready({"value": parsed})
+    except Exception:
+        # Unreachable API / timeout — events simply ship without input.
+        pass

apifyhub_sentinel-0.3.0/src/apifyhub_sentinel/_source.py

@@ -0,0 +1,50 @@
+"""Source context, ported from `sdk/sentinel/js/src/context.ts`.
+
+For each in-app frame, attach the crash line plus/minus CONTEXT_LINES so the
+dashboard can show code without the repo or source maps. Actors run their own
+source from the container filesystem, so the file is right there at capture
+time. `linecache` is stdlib and already caches per file.
+
+Same hard rules as the rest of the SDK: never raise, and stay cheap.
+"""
+from __future__ import annotations
+
+import linecache
+from typing import Any, Dict, List
+
+CONTEXT_LINES = 5  # lines above and below the crash line
+MAX_FRAMES = 8  # newest in-app frames that get context
+MAX_LINE_CHARS = 300  # truncate beyond this
+
+
+def _clip(line: str) -> str:
+    line = line.rstrip("\n")
+    return line if len(line) <= MAX_LINE_CHARS else line[:MAX_LINE_CHARS] + "…"
+
+
+def attach_source_context(frames: List[Dict[str, Any]]) -> None:
+    """Mutate `frames` (newest-last), attaching context to in-app frames."""
+    try:
+        attached = 0
+        for f in reversed(frames):
+            if attached >= MAX_FRAMES:
+                break
+            filename = f.get("filename")
+            lineno = f.get("lineno")
+            if not f.get("in_app") or not filename or not lineno or lineno < 1:
+                continue
+            lines = linecache.getlines(filename)
+            if not lines or lineno > len(lines):
+                continue
+            at = lineno - 1
+            f["pre_context"] = [
+                _clip(x) for x in lines[max(0, at - CONTEXT_LINES) : at]
+            ]
+            f["context_line"] = _clip(lines[at])
+            f["post_context"] = [
+                _clip(x) for x in lines[at + 1 : at + 1 + CONTEXT_LINES]
+            ]
+            attached += 1
+    except Exception:
+        # Context is best-effort decoration; the event ships without it.
+        pass

apifyhub_sentinel-0.3.0/src/apifyhub_sentinel/_transport.py

@@ -0,0 +1,86 @@
+"""Wire transport, ported from `sdk/sentinel/js/src/transport.ts`.
+
+Same contract as the JS sender: stdlib urllib, Bearer key in the header (never
+the body), a hard timeout, and it never raises. Sends run on daemon threads so
+capture never blocks the actor, with an in-flight registry so `flush()` can
+await delivery before the container is torn down.
+"""
+from __future__ import annotations
+
+import json
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List
+
+_TIMEOUT_S = 5.0
+
+_lock = threading.Lock()
+_in_flight: List[threading.Thread] = []
+
+
+def send_event(
+    endpoint: str, apify_hub_key: str, event: Dict[str, Any], debug: bool
+) -> None:
+    """Queue one event for delivery. Returns immediately; never raises."""
+    try:
+        body = json.dumps(event, default=str).encode("utf-8")
+    except Exception as exc:  # pragma: no cover - json failure is pathological
+        if debug:
+            print(f"[sentinel] could not serialise event: {exc}", file=sys.stderr)
+        return
+
+    t = threading.Thread(
+        target=_post, args=(endpoint, apify_hub_key, body, debug), daemon=True
+    )
+    with _lock:
+        _in_flight.append(t)
+        # Drop threads that already finished so the list cannot grow unbounded
+        # over a long run.
+        _in_flight[:] = [x for x in _in_flight if x.is_alive() or x is t]
+    t.start()
+
+
+def _post(endpoint: str, apify_hub_key: str, body: bytes, debug: bool) -> None:
+    req = urllib.request.Request(
+        endpoint,
+        data=body,
+        method="POST",
+        headers={
+            "content-type": "application/json",
+            "authorization": f"Bearer {apify_hub_key}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_TIMEOUT_S) as res:
+            if debug and not (200 <= res.status < 300):
+                print(f"[sentinel] ingest HTTP {res.status}", file=sys.stderr)
+    except urllib.error.HTTPError as exc:
+        if debug:
+            print(f"[sentinel] ingest HTTP {exc.code}", file=sys.stderr)
+    except Exception as exc:
+        if debug:
+            print(f"[sentinel] ingest failed: {exc}", file=sys.stderr)
+
+
+def flush(timeout_s: float = 2.0) -> bool:
+    """Await in-flight sends, bounded by `timeout_s`.
+
+    Returns True if everything drained in time, False otherwise. Never raises.
+    """
+    try:
+        with _lock:
+            pending = [t for t in _in_flight if t.is_alive()]
+        if not pending:
+            return True
+        deadline = time.monotonic() + timeout_s
+        for t in pending:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            t.join(timeout=remaining)
+        return not any(t.is_alive() for t in pending)
+    except Exception:
+        return False