forge-ops-tracker 0.1.0__tar.gz

forge_ops_tracker-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeOps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forge_ops_tracker-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: forge-ops-tracker
+Version: 0.1.0
+Summary: ForgeOps error tracking client: captures unhandled exceptions (Django/Flask middleware, plus explicit capture anywhere else) and delivers them to a ForgeOps instance over HTTP.
+Author: ForgeOps
+License-Expression: MIT
+Project-URL: Homepage, https://getforgeops.net
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Logging
+Classifier: Framework :: Django
+Classifier: Framework :: Flask
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: flask
+Requires-Dist: flask>=2.3; extra == "flask"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-django>=4.8; extra == "test"
+Requires-Dist: flask>=2.3; extra == "test"
+Requires-Dist: django>=4.2; extra == "test"
+Dynamic: license-file
+
+# forge-ops-tracker
+
+Python error reporting client for a private, self-hosted [ForgeOps](../../) tracker instance.
+Requires Python 3.9+. A from-scratch port of [`gems/forge_ops_tracker`](../../gems/forge_ops_tracker)
+(the Rails client) -- see that gem's README for the shared design rationale; this document only
+covers what's Python-specific.
+
+## Installation
+
+Not yet published to PyPI -- install directly from this path (or a local checkout, once split into
+its own repo):
+
+```bash
+pip install -e path/to/forge_ops/sdks/python
+```
+
+For Django or Flask integration, install the matching extra:
+
+```bash
+pip install -e "path/to/forge_ops/sdks/python[django]"
+pip install -e "path/to/forge_ops/sdks/python[flask]"
+```
+
+## Configuration
+
+Set a DSN (from a project's settings page in ForgeOps), either via the `FORGE_OPS_DSN` environment
+variable or explicitly:
+
+```python
+import forge_ops_tracker
+
+forge_ops_tracker.init(
+    dsn="https://<api_key>@your-forgeops-host/api/v1/events",  # or leave unset to read FORGE_OPS_DSN
+    release="...",
+    environment="production",
+)
+```
+
+Call `init()` once at startup -- Django's `settings.py`, or right after creating a Flask app. Any
+`Configuration` attribute can be overridden by keyword.
+
+### Django
+
+```python
+# settings.py
+import forge_ops_tracker
+
+forge_ops_tracker.init(dsn="https://<api_key>@your-forgeops-host/api/v1/events")
+
+MIDDLEWARE = [
+    ...,
+    "forge_ops_tracker.integrations.django.ForgeOpsTrackerMiddleware",
+]
+```
+
+### Flask
+
+```python
+from flask import Flask
+import forge_ops_tracker
+from forge_ops_tracker.integrations.flask import init_flask
+
+forge_ops_tracker.init(dsn="https://<api_key>@your-forgeops-host/api/v1/events")
+
+app = Flask(__name__)
+init_flask(app)
+```
+
+## What gets reported automatically, and what doesn't
+
+**An exception that crashes a request needs no further wiring at all.** The Django middleware's
+`process_exception` hook and Flask's `got_request_exception` signal both fire for anything that
+propagates uncaught out of a view, then let the framework handle it exactly as if this client
+weren't installed.
+
+**An exception your own code catches and handles is different -- neither integration ever sees
+it**, since it never propagates far enough to reach either hook:
+
+```python
+try:
+    charge_card(order)
+except CardError as e:
+    logger.warning("card declined: %s", e)
+    # ForgeOps never sees this -- caught locally, never reaches the
+    # middleware/signal at all.
+```
+
+There's no Django/Flask-wide equivalent to Rails' `Rails.error.handle` here -- report it explicitly
+instead, right at the catch site:
+
+```python
+except CardError as e:
+    forge_ops_tracker.capture_exception(e, context={"order_id": order.id})
+    logger.warning("card declined: %s", e)
+```
+
+Called with no arguments, `capture_exception()` picks up whichever exception is currently being
+handled (same as a bare `raise` inside an `except:` block), so it usually reads as just
+`forge_ops_tracker.capture_exception()` from inside the block that already caught it.
+
+### Outside a web request (scripts, management commands, workers)
+
+`init()` also installs a `sys.excepthook` wrapper by default (`Configuration.install_excepthook`,
+`True` unless set otherwise), which reports anything that crashes the whole interpreter -- a plain
+script, a Django management command, a worker's own top-level loop -- with no wiring needed, the
+same "unhandled needs no wiring" case the Django/Flask integrations cover for web requests. It
+still calls whatever `sys.excepthook` was already installed afterward, so it never changes program
+behavior. This does **not** catch a web request's unhandled exception under a real WSGI server
+(Gunicorn/uWSGI catch that themselves per-request, long before it would ever reach the interpreter
+level) -- that's what the Django/Flask integrations are for.
+
+Delivery happens on a background thread with a bounded queue and a short per-request HTTP timeout
+(`Configuration.timeout`, 2s default). Every failure mode -- network errors, timeouts, a full queue,
+a malformed DSN -- is caught and dropped rather than raised, so a broken or unreachable tracker can
+never take down the host app. The worker thread starts lazily, on first push, not at import time --
+Gunicorn (prefork) and uWSGI commonly fork worker processes *after* the application has already
+loaded, which would leave an eagerly-started thread dead in every forked child; starting fresh on
+first push means each forked worker gets its own live thread regardless of when it was forked
+relative to import.
+
+## `in_app` backtrace frames
+
+Unlike the .NET SDK (where a compiled assembly's file path never matches its original source
+location), Python runs interpreted directly from real `.py` files on disk, so file-path matching
+against `Configuration.app_root` works the same way it does in the Ruby gem's `Rails.root`
+comparison. Defaults to the current working directory; set it explicitly if that doesn't match your
+app's actual layout (a WSGI server started from a different directory than your app's root, for
+instance). Standard-library and installed-package (`site-packages`/`dist-packages`) frames are
+never marked `in_app`, regardless of `app_root`.
+
+## PII scrubbing
+
+Same behavior as the Ruby gem: the message, backtrace, and any context/tags you attach are scanned
+for likely personal data -- email addresses, formatted SSNs/credit cards, known API key/token
+formats, and anything under a suspiciously-named key (`password`, `api_key`, `ssn`, and similar) --
+and redacted before the payload ever leaves this process. ForgeOps itself scrubs again on arrival
+regardless, so this is a second, earlier layer, not the only one.
+
+To disable it:
+
+```python
+forge_ops_tracker.init(dsn="...", scrub_pii=False)
+```
+
+## Running the tests
+
+```bash
+cd sdks/python
+python3 -m venv .venv
+./.venv/bin/pip install -e ".[test]"
+./.venv/bin/python -m pytest
+./.venv/bin/ruff check src tests
+```

forge_ops_tracker-0.1.0/README.md

@@ -0,0 +1,153 @@
+# forge-ops-tracker
+
+Python error reporting client for a private, self-hosted [ForgeOps](../../) tracker instance.
+Requires Python 3.9+. A from-scratch port of [`gems/forge_ops_tracker`](../../gems/forge_ops_tracker)
+(the Rails client) -- see that gem's README for the shared design rationale; this document only
+covers what's Python-specific.
+
+## Installation
+
+Not yet published to PyPI -- install directly from this path (or a local checkout, once split into
+its own repo):
+
+```bash
+pip install -e path/to/forge_ops/sdks/python
+```
+
+For Django or Flask integration, install the matching extra:
+
+```bash
+pip install -e "path/to/forge_ops/sdks/python[django]"
+pip install -e "path/to/forge_ops/sdks/python[flask]"
+```
+
+## Configuration
+
+Set a DSN (from a project's settings page in ForgeOps), either via the `FORGE_OPS_DSN` environment
+variable or explicitly:
+
+```python
+import forge_ops_tracker
+
+forge_ops_tracker.init(
+    dsn="https://<api_key>@your-forgeops-host/api/v1/events",  # or leave unset to read FORGE_OPS_DSN
+    release="...",
+    environment="production",
+)
+```
+
+Call `init()` once at startup -- Django's `settings.py`, or right after creating a Flask app. Any
+`Configuration` attribute can be overridden by keyword.
+
+### Django
+
+```python
+# settings.py
+import forge_ops_tracker
+
+forge_ops_tracker.init(dsn="https://<api_key>@your-forgeops-host/api/v1/events")
+
+MIDDLEWARE = [
+    ...,
+    "forge_ops_tracker.integrations.django.ForgeOpsTrackerMiddleware",
+]
+```
+
+### Flask
+
+```python
+from flask import Flask
+import forge_ops_tracker
+from forge_ops_tracker.integrations.flask import init_flask
+
+forge_ops_tracker.init(dsn="https://<api_key>@your-forgeops-host/api/v1/events")
+
+app = Flask(__name__)
+init_flask(app)
+```
+
+## What gets reported automatically, and what doesn't
+
+**An exception that crashes a request needs no further wiring at all.** The Django middleware's
+`process_exception` hook and Flask's `got_request_exception` signal both fire for anything that
+propagates uncaught out of a view, then let the framework handle it exactly as if this client
+weren't installed.
+
+**An exception your own code catches and handles is different -- neither integration ever sees
+it**, since it never propagates far enough to reach either hook:
+
+```python
+try:
+    charge_card(order)
+except CardError as e:
+    logger.warning("card declined: %s", e)
+    # ForgeOps never sees this -- caught locally, never reaches the
+    # middleware/signal at all.
+```
+
+There's no Django/Flask-wide equivalent to Rails' `Rails.error.handle` here -- report it explicitly
+instead, right at the catch site:
+
+```python
+except CardError as e:
+    forge_ops_tracker.capture_exception(e, context={"order_id": order.id})
+    logger.warning("card declined: %s", e)
+```
+
+Called with no arguments, `capture_exception()` picks up whichever exception is currently being
+handled (same as a bare `raise` inside an `except:` block), so it usually reads as just
+`forge_ops_tracker.capture_exception()` from inside the block that already caught it.
+
+### Outside a web request (scripts, management commands, workers)
+
+`init()` also installs a `sys.excepthook` wrapper by default (`Configuration.install_excepthook`,
+`True` unless set otherwise), which reports anything that crashes the whole interpreter -- a plain
+script, a Django management command, a worker's own top-level loop -- with no wiring needed, the
+same "unhandled needs no wiring" case the Django/Flask integrations cover for web requests. It
+still calls whatever `sys.excepthook` was already installed afterward, so it never changes program
+behavior. This does **not** catch a web request's unhandled exception under a real WSGI server
+(Gunicorn/uWSGI catch that themselves per-request, long before it would ever reach the interpreter
+level) -- that's what the Django/Flask integrations are for.
+
+Delivery happens on a background thread with a bounded queue and a short per-request HTTP timeout
+(`Configuration.timeout`, 2s default). Every failure mode -- network errors, timeouts, a full queue,
+a malformed DSN -- is caught and dropped rather than raised, so a broken or unreachable tracker can
+never take down the host app. The worker thread starts lazily, on first push, not at import time --
+Gunicorn (prefork) and uWSGI commonly fork worker processes *after* the application has already
+loaded, which would leave an eagerly-started thread dead in every forked child; starting fresh on
+first push means each forked worker gets its own live thread regardless of when it was forked
+relative to import.
+
+## `in_app` backtrace frames
+
+Unlike the .NET SDK (where a compiled assembly's file path never matches its original source
+location), Python runs interpreted directly from real `.py` files on disk, so file-path matching
+against `Configuration.app_root` works the same way it does in the Ruby gem's `Rails.root`
+comparison. Defaults to the current working directory; set it explicitly if that doesn't match your
+app's actual layout (a WSGI server started from a different directory than your app's root, for
+instance). Standard-library and installed-package (`site-packages`/`dist-packages`) frames are
+never marked `in_app`, regardless of `app_root`.
+
+## PII scrubbing
+
+Same behavior as the Ruby gem: the message, backtrace, and any context/tags you attach are scanned
+for likely personal data -- email addresses, formatted SSNs/credit cards, known API key/token
+formats, and anything under a suspiciously-named key (`password`, `api_key`, `ssn`, and similar) --
+and redacted before the payload ever leaves this process. ForgeOps itself scrubs again on arrival
+regardless, so this is a second, earlier layer, not the only one.
+
+To disable it:
+
+```python
+forge_ops_tracker.init(dsn="...", scrub_pii=False)
+```
+
+## Running the tests
+
+```bash
+cd sdks/python
+python3 -m venv .venv
+./.venv/bin/pip install -e ".[test]"
+./.venv/bin/python -m pytest
+./.venv/bin/ruff check src tests
+```

forge_ops_tracker-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "forge-ops-tracker"
+version = "0.1.0"
+description = "ForgeOps error tracking client: captures unhandled exceptions (Django/Flask middleware, plus explicit capture anywhere else) and delivers them to a ForgeOps instance over HTTP."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = [ "LICENSE.txt" ]
+authors = [ { name = "ForgeOps" } ]
+dependencies = []
+# No "License :: OSI Approved :: MIT License" classifier -- superseded by the license = "MIT"
+# SPDX expression above (PEP 639); setuptools now rejects having both.
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: System :: Logging",
+    "Framework :: Django",
+    "Framework :: Flask",
+]
+
+# source_code_uri/repository/changelog deliberately omitted -- the monorepo this currently
+# lives in is private, so a link to it would 404 for anyone outside the team. Add these once
+# this is split into its own public repo (see gems/forge_ops_tracker's gemspec for the same
+# reasoning, applied there first).
+[project.urls]
+Homepage = "https://getforgeops.net"
+
+[project.optional-dependencies]
+django = ["django>=4.2"]
+flask = ["flask>=2.3"]
+test = ["pytest>=8", "pytest-django>=4.8", "flask>=2.3", "django>=4.2"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.django_settings"
+testpaths = ["tests"]

forge_ops_tracker-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

forge_ops_tracker-0.1.0/src/forge_ops_tracker/__init__.py

@@ -0,0 +1,103 @@
+"""ForgeOps error tracking client.
+
+    import forge_ops_tracker
+    forge_ops_tracker.init(dsn="https://<api_key>@your-forgeops-host/api/v1/events")
+
+See the README for Django/Flask integration and what gets captured
+automatically vs. what needs an explicit capture_exception() call.
+"""
+
+import sys
+import threading
+
+from .client import Client
+from .configuration import Configuration
+from .delivery_queue import DeliveryQueue
+from .event_builder import EventBuilder
+from .reporter import Reporter
+
+__all__ = ["Configuration", "capture_exception", "init"]
+
+_configuration = None
+_reporter = None
+_lock = threading.Lock()
+_original_excepthook = None
+
+
+def _state():
+    global _configuration, _reporter
+    if _reporter is None:
+        with _lock:
+            if _reporter is None:
+                _configuration = Configuration()
+                client = Client(_configuration)
+                delivery_queue = DeliveryQueue(_configuration, client)
+                _reporter = Reporter(_configuration, EventBuilder(_configuration), delivery_queue)
+    return _configuration, _reporter
+
+
+def init(dsn=None, **overrides):
+    """Configure the client. Call once at startup (Django settings.py, or
+    right after creating a Flask app). Any Configuration attribute can be
+    overridden by keyword, e.g. init(dsn=..., release=..., environment=...).
+    """
+    configuration, _ = _state()
+    if dsn is not None:
+        configuration.dsn = dsn
+    for key, value in overrides.items():
+        if not hasattr(configuration, key):
+            raise TypeError(f"Configuration has no attribute {key!r}")
+        setattr(configuration, key, value)
+
+    if configuration.install_excepthook:
+        _install_excepthook()
+
+    return configuration
+
+
+def capture_exception(exc=None, context=None):
+    """Report an exception you've already caught. `exc` defaults to
+    whichever exception is currently being handled, so this can usually
+    just be called as capture_exception() from inside an `except:` block."""
+    if exc is None:
+        exc = sys.exc_info()[1]
+    if exc is None:
+        return
+
+    _, reporter = _state()
+    reporter.report(exc, context=context)
+
+
+def _install_excepthook():
+    # Reports anything that crashes the whole interpreter (a plain
+    # script, a management command, a worker's own top-level loop) with
+    # no further wiring -- the same "unhandled needs no wiring" case
+    # Rails.error/ASP.NET Core's middleware cover automatically. This does
+    # *not* catch a web request's unhandled exception under a WSGI
+    # server -- Django/Flask catch that themselves before it ever reaches
+    # here, which is what the integrations in forge_ops_tracker.integrations
+    # are for.
+    global _original_excepthook
+    if _original_excepthook is not None:
+        return  # already installed
+
+    _original_excepthook = sys.excepthook
+
+    def _excepthook(exc_type, exc_value, exc_tb):
+        try:
+            capture_exception(exc_value)
+        finally:
+            _original_excepthook(exc_type, exc_value, exc_tb)
+
+    sys.excepthook = _excepthook
+
+
+def _reset_for_testing():
+    """Not part of the public API -- resets module-level state between
+    test cases."""
+    global _configuration, _reporter, _original_excepthook
+    if _original_excepthook is not None:
+        sys.excepthook = _original_excepthook
+    _configuration = None
+    _reporter = None
+    _original_excepthook = None

forge_ops_tracker-0.1.0/src/forge_ops_tracker/client.py

@@ -0,0 +1,41 @@
+"""Delivers one payload over HTTP. Every failure mode -- DNS, connection,
+timeout, TLS, a non-2xx response -- is caught here and turned into a
+`False` return rather than a raised exception, since a broken or
+unreachable tracker must never be able to break the host app. Ported
+from gems/forge_ops_tracker/lib/forge_ops_tracker/client.rb.
+
+Uses only the standard library (urllib), not `requests` -- same reason
+the Ruby gem uses plain Net::HTTP rather than a gem dependency: this has
+to work in any host app without adding a dependency of its own.
+"""
+
+import json
+import urllib.error
+import urllib.request
+
+
+class Client:
+    def __init__(self, configuration):
+        self._configuration = configuration
+
+    def deliver(self, payload):
+        uri = self._configuration.ingestion_uri()
+        if not uri:
+            return False
+
+        try:
+            body = json.dumps(payload).encode("utf-8")
+            request = urllib.request.Request(
+                uri,
+                data=body,
+                method="POST",
+                headers={
+                    "Authorization": f"Bearer {self._configuration.api_key}",
+                    "Content-Type": "application/json",
+                },
+            )
+            with urllib.request.urlopen(request, timeout=self._configuration.timeout) as response:
+                return 200 <= response.status < 300
+        except Exception as e:  # noqa: BLE001 -- deliberately broad: a broken/unreachable tracker must never break the host app
+            self._configuration.logger.debug("[forge_ops_tracker] delivery failed: %s: %s", type(e).__name__, e)
+            return False

forge_ops_tracker-0.1.0/src/forge_ops_tracker/configuration.py

@@ -0,0 +1,82 @@
+"""Holds a single ForgeOps DSN plus everything else the client needs to
+build and deliver events. Mirrors gems/forge_ops_tracker's Configuration --
+a single Sentry-style DSN string carries both the ingestion URL and the
+project's api_key: "https://<api_key>@host/api/v1/events".
+"""
+
+import logging
+import os
+import socket
+from urllib.parse import unquote, urlsplit, urlunsplit
+
+
+class Configuration:
+    def __init__(self):
+        self.dsn = os.environ.get("FORGE_OPS_DSN")
+        self.environment = os.environ.get("FORGE_OPS_ENVIRONMENT", "development")
+        self.release = os.environ.get("FORGE_OPS_RELEASE")
+        self.server_name = _safe_hostname()
+
+        # Used to decide whether a backtrace frame is "in_app": a frame's
+        # file path is compared against this root. Unlike the .NET SDK
+        # (where a compiled assembly's file path never matches its
+        # original source location), Python runs interpreted directly
+        # from real .py files on disk, so file-path matching is the
+        # correct approach here too, same as the Ruby gem's Rails.root
+        # comparison. Defaults to the current working directory; set
+        # explicitly if that doesn't match your app's actual layout (a
+        # WSGI server started from a different directory, for instance).
+        self.app_root = os.getcwd()
+
+        self.enabled_environments = {"production", "staging"}
+        self.queue_size = 1000
+        self.timeout = 2.0  # seconds
+        self.scrub_pii = True
+        self.logger = logging.getLogger("forge_ops_tracker")
+
+        # Reports anything that crashes the whole interpreter (a plain
+        # script, a management command) with zero extra wiring, the same
+        # way an unhandled Rails/ASP.NET Core request is covered
+        # automatically elsewhere -- see _install_excepthook in __init__.py.
+        # Doesn't change program behavior (the original hook still runs
+        # afterward), so on by default is safe; set False to opt out.
+        self.install_excepthook = True
+
+    @property
+    def api_key(self):
+        parsed = self._parsed_dsn()
+        if parsed is None or not parsed.username:
+            return None
+        return unquote(parsed.username)
+
+    def ingestion_uri(self):
+        """The ingestion URL with credentials stripped out (they travel as
+        the Authorization header instead, not embedded in the request
+        URI)."""
+        parsed = self._parsed_dsn()
+        if parsed is None:
+            return None
+
+        netloc = parsed.hostname or ""
+        if parsed.port:
+            netloc = f"{netloc}:{parsed.port}"
+        return urlunsplit((parsed.scheme, netloc, parsed.path, parsed.query, ""))
+
+    def is_enabled(self):
+        return bool(self.dsn) and bool(self.api_key) and self.environment in self.enabled_environments
+
+    def _parsed_dsn(self):
+        if not self.dsn:
+            return None
+        # urlsplit never raises on malformed input (verified directly,
+        # not assumed) -- a bad DSN just parses to an empty netloc, which
+        # api_key/ingestion_uri already handle by returning None.
+        result = urlsplit(self.dsn)
+        return result if result.scheme else None
+
+
+def _safe_hostname():
+    try:
+        return socket.gethostname()
+    except Exception:  # noqa: BLE001 -- hostname lookup must never be able to crash the host app
+        return None

forge_ops_tracker-0.1.0/src/forge_ops_tracker/delivery_queue.py

@@ -0,0 +1,55 @@
+"""A small in-process background thread + bounded queue, so delivery
+never blocks the caller that raised the error and never depends on the
+host app having any particular job backend configured. Ported from
+gems/forge_ops_tracker/lib/forge_ops_tracker/delivery_queue.rb.
+
+The worker thread is started lazily, on first push, not at import/
+construction time -- deliberately mirroring the Ruby gem rather than the
+.NET SDK's eager start. Gunicorn (prefork) and uWSGI commonly fork worker
+processes *after* the application (and this module) has already loaded,
+which would leave an eagerly-started thread dead in every forked child --
+the exact hazard the Ruby gem's own lazy start avoids for Puma. Starting
+fresh on first push means each forked worker gets its own live thread
+regardless of when it was forked relative to import time.
+"""
+
+import queue
+import threading
+
+
+class DeliveryQueue:
+    def __init__(self, configuration, client):
+        self._configuration = configuration
+        self._client = client
+        self._queue = queue.Queue(maxsize=max(1, configuration.queue_size))
+        self._thread = None
+        self._start_lock = threading.Lock()
+
+    def push(self, payload):
+        self._ensure_worker_started()
+        try:
+            self._queue.put_nowait(payload)
+            return True
+        except queue.Full:
+            self._configuration.logger.debug("[forge_ops_tracker] delivery queue full, dropping event")
+            return False
+
+    def _ensure_worker_started(self):
+        if self._thread is not None and self._thread.is_alive():
+            return
+
+        with self._start_lock:
+            if self._thread is not None and self._thread.is_alive():
+                return
+            self._thread = threading.Thread(target=self._run, daemon=True)
+            self._thread.start()
+
+    def _run(self):
+        while True:
+            payload = self._queue.get()
+            try:
+                self._client.deliver(payload)
+            except Exception as e:  # noqa: BLE001 -- per-item, so one bad delivery can't kill the worker for every event after it
+                # Per-item, not wrapping the whole loop: one bad delivery
+                # must not kill the worker for every event after it.
+                self._configuration.logger.debug("[forge_ops_tracker] delivery worker error: %s: %s", type(e).__name__, e)