lumonox-sdk 0.2.3__tar.gz

lumonox_sdk-0.2.3/.gitignore

@@ -0,0 +1,73 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.venv/
+venv/
+ENV/
+
+# uv
+.uv/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Node / Next.js (frontend)
+node_modules/
+.next/
+out/
+.turbo/
+*.tsbuildinfo
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.*
+!.env.example
+!.env.lumonox.example
+
+# Local SQLite (dev)
+*.db
+
+# Logs
+*.log
+
+.lumonox/
+# Legacy local data dir name (pre-rename checkouts); never commit.
+.autopulse/
+backend/.autopulse/
+sdk/.autopulse/
+
+# Local stray copies of dashboard static export (canonical build is frontend/out)
+sdk/src/lumonox/ui/
+
+# Hatch sdist staging for shipped wheels (never commit baked export under src)
+backend/src/lumonox_backend/dashboard_static/

lumonox_sdk-0.2.3/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to the **Lumonox** Python SDK are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+for public API and packaging.
+
+## [Unreleased]
+
+## [0.2.3] - 2026-05-11
+
+### Packaging
+
+- **`[stack]`** extra depends on **`lumonox>=0.2.5`** (aligned with the **0.2.5** API wheel on PyPI).
+
+## [0.2.2] - 2026-05-11
+
+### Packaging
+
+- **`[stack]`** extra depends on **`lumonox>=0.2.1`** (PyPI project **`lumonox`** for the API + bundled dashboard; replaces the prior **`lumonox-api`** distribution name).
+
+## [0.2.1] - 2026-05-10
+
+### Changed
+
+- **Dashboard (bundled in `lumonox-api`):** settings composition and hooks, shared session-scoped dashboard fetches, stricter JSON guards for dashboard query responses, chart and query-toolbar accessibility improvements, extended Vitest/Playwright smoke coverage, and frontend README/ESLint contributor guardrails (see `docs/FRONTEND_MULTI_LANE_REVIEW_TASK_PLAN.md`).
+- **Release tooling:** `/dashboard` first-load uncompressed JS bundle budget headroom updated to match current Next.js output (`frontend/scripts/checkRouteBundleBudgets.mjs`).
+
+### Packaging
+
+- **`[stack]`** extra requires **`lumonox-api>=0.2.1`**.
+
+## [0.2.0] - 2026-05-09
+
+### Changed
+
+- **Branding and packaging:** project and PyPI distributions are **Lumonox** (`lumonox-sdk`, `lumonox-api`); Python packages are **`lumonox`** (SDK) and **`lumonox_backend`** (API). Environment variables use the **`LUMONOX_`** prefix; dashboard static export mounts at **`/lumonox/ui/`**.
+
+### Breaking
+
+- **Database migrations:** Alembic history is replaced by a **single `initial` revision** that creates the full schema from current ORM models. Existing SQLite dev databases with stale `alembic_version` rows may be **recreated** on startup when migrations cannot resolve the old revision (see `upgrade_to_head` in `lumonox_backend.database.migrations`). Plan Postgres upgrades explicitly (`alembic stamp` / dump-restore) before deploying.
+
+### Packaging
+
+- **`[stack]`** extra requires **`lumonox-api>=0.2.0`**.
+
+## [0.1.4] - 2026-05-08
+
+### Packaging
+
+- **`[stack]`** extra requires **`lumonox-api>=0.1.5`** (aligned with the current API wheel release train).
+
+## [0.1.3] - 2026-05-08
+
+### Packaging
+
+- **`[stack]`** extra now depends on **`lumonox-api>=0.1.4`** (PyPI name for the API + bundled dashboard).
+
+## [0.1.2] - 2026-05-08
+
+### Added
+
+- Optional extra **`[stack]`**: depends on the API distribution so `pip install "lumonox-sdk[stack]"` installs the API (with bundled dashboard) plus this SDK.
+
+### Packaging
+
+- **PyPI distribution name** for the SDK remains **`lumonox-sdk`** (import package **`lumonox`**).
+
+### Security
+
+- **Breaking / privacy:** `monitor()` now defaults `capture_headers` and `capture_query_params` to **off** unless enabled via kwargs or `LUMONOX_CAPTURE_HEADERS` / `LUMONOX_CAPTURE_QUERY_PARAMS`. Reduces accidental PII in events.
+- **Embedded:** if `.env.lumonox` cannot be written, the SDK no longer falls back to a repo-known API key; it uses the generated key from the failed write attempt for that process and logs remediation steps.
+
+### Fixed
+
+- Middleware tests using a stub dispatcher no longer assume a private `_send_enabled` attribute on arbitrary dispatcher objects (`getattr` fallback).

lumonox_sdk-0.2.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lumonox contributors
+
+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.

lumonox_sdk-0.2.3/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: lumonox-sdk
+Version: 0.2.3
+Summary: FastAPI observability SDK for Lumonox
+Project-URL: Homepage, https://github.com/sintimaski/lumonox
+Project-URL: Repository, https://github.com/sintimaski/lumonox
+Project-URL: Documentation, https://github.com/sintimaski/lumonox/blob/main/sdk/README.md
+Project-URL: Changelog, https://github.com/sintimaski/lumonox/blob/main/sdk/CHANGELOG.md
+Project-URL: Issues, https://github.com/sintimaski/lumonox/issues
+Author: Lumonox maintainers
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apm,errors,fastapi,monitoring,observability,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: psutil>=6.0.0
+Provides-Extra: stack
+Requires-Dist: lumonox>=0.2.5; extra == 'stack'
+Description-Content-Type: text/markdown
+
+# Lumonox SDK (Python)
+
+Lumonox SDK instruments a FastAPI app and sends request/error events to Lumonox with safe defaults.
+
+## Install
+
+| Goal | PyPI one-liner | Import / process |
+|------|-----------------|------------------|
+| **API + bundled dashboard UI** (ingest, dashboard, static export under `/lumonox/ui/`) | `pip install lumonox` | `import lumonox_backend` · run `uvicorn lumonox_backend.main:app` |
+| **Instrument your FastAPI app** (send-only SDK) | `pip install lumonox-sdk` | `from lumonox import lumonox` |
+| **API + UI + SDK in one environment** | `pip install "lumonox-sdk[stack]"` | both of the above |
+
+`uv add` works the same (`uv add lumonox`, `uv add "lumonox-sdk[stack]"`, …).
+
+**From a git checkout** (offline wheels from repo root):
+
+```bash
+./scripts/build_sdk_release_wheels.sh   # writes dist/wheels/*.whl
+pip install dist/wheels/lumonox-*.whl dist/wheels/lumonox_sdk-*.whl
+```
+
+## Publish to PyPI
+
+Artifacts are standard **wheel + sdist** from the workspace root (`hatchling` via `uv build`):
+
+```bash
+uv build --package lumonox-sdk -o dist/pypi-sdk
+python -m pip install twine   # once
+twine check dist/pypi-sdk/*
+twine upload dist/pypi-sdk/*
+```
+
+**Recommended:** use [trusted publishing](https://docs.pypi.org/trusted-publishers/) from GitHub Actions instead of storing a long-lived PyPI token in CI secrets:
+
+- **SDK:** `.github/workflows/publish-lumonox-sdk-pypi.yml` → project **`lumonox-sdk`**
+- **API + bundled UI:** `.github/workflows/publish-lumonox-pypi.yml` → project **`lumonox`**
+
+**On `main`:** the SDK workflow runs when `sdk/pyproject.toml`, `sdk/src/**`, `sdk/README.md`, or `sdk/LICENSE` change. The **`lumonox`** publish workflow runs when `backend/pyproject.toml`, `backend/src/**`, or `frontend/**` change. Both upload **only when** the corresponding `[project] version` is **not already** on PyPI.
+
+**`lumonox-sdk[stack]` on PyPI:** publish **`lumonox`** first (or same release train) so the extra can resolve **`lumonox>=0.2.5`**.
+
+**One-time on PyPI:** create projects **`lumonox-sdk`** and **`lumonox`**, add trusted publishers for each workflow, then merge version bumps or run workflows manually.
+
+## Integration
+
+```python
+from fastapi import FastAPI
+from lumonox import lumonox, monitor
+
+app = FastAPI()
+lumonox(app)  # recommended default
+# monitor(app)  # backwards-compatible alias for existing integrations
+```
+
+`lumonox()` defaults **`environment` to `development`** so request events match common dashboard server-scope filters. Use `lumonox(app, environment="production")` when you need production labels.
+
+By default, `lumonox()` (and `monitor()` for existing integrations) target a remote Lumonox project (set `LUMONOX_API_KEY` / `LUMONOX_INGEST_URL`). It uses bounded in-memory buffering, async background sending, and silent failure behavior so host apps stay healthy if Lumonox is unavailable.
+
+If **either** variable is missing, the sender stays off: middleware still runs, but **no events are enqueued** (minimal overhead). A **one-time `WARNING`** is emitted on process startup so misconfiguration is obvious without breaking the host app.
+
+## Key runtime controls
+
+- `LUMONOX_API_KEY`
+- `LUMONOX_INGEST_URL` (or `LUMONOX_ENDPOINT`)
+- `LUMONOX_FLUSH_INTERVAL_SECONDS`
+- `LUMONOX_BATCH_MAX_EVENTS`
+- `LUMONOX_MAX_QUEUE_SIZE`
+- `LUMONOX_DEBUG`
+- `LUMONOX_REQUEST_SAMPLE_RATE` (`0.0`-`1.0`; default `1.0`)
+- `LUMONOX_IGNORE_PATH_PREFIXES` (comma-separated, default `/health,/ready`)
+- `LUMONOX_CAPTURE_HEADERS` — when `true`/`1`/`yes`, capture request headers in events (default **off** for production-safe privacy).
+- `LUMONOX_CAPTURE_QUERY_PARAMS` — when truthy, capture query parameters (default **off**).
+
+`lumonox()` and `monitor()` support explicit kwargs for runtime behavior:
+
+- `capture_headers` (default follows `LUMONOX_CAPTURE_HEADERS`, else **False**)
+- `capture_query_params` (default follows `LUMONOX_CAPTURE_QUERY_PARAMS`, else **False**)
+- `request_sample_rate` (float `0.0`-`1.0`, keeps 5xx/error capture unsampled)
+- `ignore_path_prefixes` (tuple/list of path prefixes to skip, e.g. `("/health", "/ready")`)
+- `scrub_keys` (additional sensitive keys to redact)
+- `queue_maxsize`, `batch_size`, `flush_interval_s`, `max_retries`, `retry_backoff_s`
+
+## Security defaults
+
+- Sensitive keys are scrubbed before send.
+- **Headers and query strings are not captured unless explicitly enabled** (kwargs or env vars above)—opt in when debugging, not in production, unless you accept the PII risk.
+- Middleware captures error context and re-raises original exceptions.
+
+## Troubleshooting (“no events”)
+
+1. Confirm `LUMONOX_API_KEY` and `LUMONOX_INGEST_URL` are both set for `lumonox()` (see startup `WARNING` when remote send is disabled).
+2. Enable `LUMONOX_DEBUG=1` temporarily to surface queue drops or send failures on stderr.
+3. Check dashboard server-scope filters (environment / service) vs the `environment` and `service_name` fields you send from the SDK.
+4. Dashboard shows traffic but **requests/errors look empty** while DuckDB tools show rows: you likely opened a **different** DuckDB file than the API. Set `LUMONOX_DATA_DIR` or an absolute `LUMONOX_DUCKDB_PATH` on the backend and confirm startup logs (`Startup settings [event_store]: … duckdb_path=…`).
+
+Canonical behavior and constraints are defined in `DEVELOPMENT.md`.

lumonox_sdk-0.2.3/README.md

@@ -0,0 +1,96 @@
+# Lumonox SDK (Python)
+
+Lumonox SDK instruments a FastAPI app and sends request/error events to Lumonox with safe defaults.
+
+## Install
+
+| Goal | PyPI one-liner | Import / process |
+|------|-----------------|------------------|
+| **API + bundled dashboard UI** (ingest, dashboard, static export under `/lumonox/ui/`) | `pip install lumonox` | `import lumonox_backend` · run `uvicorn lumonox_backend.main:app` |
+| **Instrument your FastAPI app** (send-only SDK) | `pip install lumonox-sdk` | `from lumonox import lumonox` |
+| **API + UI + SDK in one environment** | `pip install "lumonox-sdk[stack]"` | both of the above |
+
+`uv add` works the same (`uv add lumonox`, `uv add "lumonox-sdk[stack]"`, …).
+
+**From a git checkout** (offline wheels from repo root):
+
+```bash
+./scripts/build_sdk_release_wheels.sh   # writes dist/wheels/*.whl
+pip install dist/wheels/lumonox-*.whl dist/wheels/lumonox_sdk-*.whl
+```
+
+## Publish to PyPI
+
+Artifacts are standard **wheel + sdist** from the workspace root (`hatchling` via `uv build`):
+
+```bash
+uv build --package lumonox-sdk -o dist/pypi-sdk
+python -m pip install twine   # once
+twine check dist/pypi-sdk/*
+twine upload dist/pypi-sdk/*
+```
+
+**Recommended:** use [trusted publishing](https://docs.pypi.org/trusted-publishers/) from GitHub Actions instead of storing a long-lived PyPI token in CI secrets:
+
+- **SDK:** `.github/workflows/publish-lumonox-sdk-pypi.yml` → project **`lumonox-sdk`**
+- **API + bundled UI:** `.github/workflows/publish-lumonox-pypi.yml` → project **`lumonox`**
+
+**On `main`:** the SDK workflow runs when `sdk/pyproject.toml`, `sdk/src/**`, `sdk/README.md`, or `sdk/LICENSE` change. The **`lumonox`** publish workflow runs when `backend/pyproject.toml`, `backend/src/**`, or `frontend/**` change. Both upload **only when** the corresponding `[project] version` is **not already** on PyPI.
+
+**`lumonox-sdk[stack]` on PyPI:** publish **`lumonox`** first (or same release train) so the extra can resolve **`lumonox>=0.2.5`**.
+
+**One-time on PyPI:** create projects **`lumonox-sdk`** and **`lumonox`**, add trusted publishers for each workflow, then merge version bumps or run workflows manually.
+
+## Integration
+
+```python
+from fastapi import FastAPI
+from lumonox import lumonox, monitor
+
+app = FastAPI()
+lumonox(app)  # recommended default
+# monitor(app)  # backwards-compatible alias for existing integrations
+```
+
+`lumonox()` defaults **`environment` to `development`** so request events match common dashboard server-scope filters. Use `lumonox(app, environment="production")` when you need production labels.
+
+By default, `lumonox()` (and `monitor()` for existing integrations) target a remote Lumonox project (set `LUMONOX_API_KEY` / `LUMONOX_INGEST_URL`). It uses bounded in-memory buffering, async background sending, and silent failure behavior so host apps stay healthy if Lumonox is unavailable.
+
+If **either** variable is missing, the sender stays off: middleware still runs, but **no events are enqueued** (minimal overhead). A **one-time `WARNING`** is emitted on process startup so misconfiguration is obvious without breaking the host app.
+
+## Key runtime controls
+
+- `LUMONOX_API_KEY`
+- `LUMONOX_INGEST_URL` (or `LUMONOX_ENDPOINT`)
+- `LUMONOX_FLUSH_INTERVAL_SECONDS`
+- `LUMONOX_BATCH_MAX_EVENTS`
+- `LUMONOX_MAX_QUEUE_SIZE`
+- `LUMONOX_DEBUG`
+- `LUMONOX_REQUEST_SAMPLE_RATE` (`0.0`-`1.0`; default `1.0`)
+- `LUMONOX_IGNORE_PATH_PREFIXES` (comma-separated, default `/health,/ready`)
+- `LUMONOX_CAPTURE_HEADERS` — when `true`/`1`/`yes`, capture request headers in events (default **off** for production-safe privacy).
+- `LUMONOX_CAPTURE_QUERY_PARAMS` — when truthy, capture query parameters (default **off**).
+
+`lumonox()` and `monitor()` support explicit kwargs for runtime behavior:
+
+- `capture_headers` (default follows `LUMONOX_CAPTURE_HEADERS`, else **False**)
+- `capture_query_params` (default follows `LUMONOX_CAPTURE_QUERY_PARAMS`, else **False**)
+- `request_sample_rate` (float `0.0`-`1.0`, keeps 5xx/error capture unsampled)
+- `ignore_path_prefixes` (tuple/list of path prefixes to skip, e.g. `("/health", "/ready")`)
+- `scrub_keys` (additional sensitive keys to redact)
+- `queue_maxsize`, `batch_size`, `flush_interval_s`, `max_retries`, `retry_backoff_s`
+
+## Security defaults
+
+- Sensitive keys are scrubbed before send.
+- **Headers and query strings are not captured unless explicitly enabled** (kwargs or env vars above)—opt in when debugging, not in production, unless you accept the PII risk.
+- Middleware captures error context and re-raises original exceptions.
+
+## Troubleshooting (“no events”)
+
+1. Confirm `LUMONOX_API_KEY` and `LUMONOX_INGEST_URL` are both set for `lumonox()` (see startup `WARNING` when remote send is disabled).
+2. Enable `LUMONOX_DEBUG=1` temporarily to surface queue drops or send failures on stderr.
+3. Check dashboard server-scope filters (environment / service) vs the `environment` and `service_name` fields you send from the SDK.
+4. Dashboard shows traffic but **requests/errors look empty** while DuckDB tools show rows: you likely opened a **different** DuckDB file than the API. Set `LUMONOX_DATA_DIR` or an absolute `LUMONOX_DUCKDB_PATH` on the backend and confirm startup logs (`Startup settings [event_store]: … duckdb_path=…`).
+
+Canonical behavior and constraints are defined in `DEVELOPMENT.md`.

lumonox_sdk-0.2.3/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "lumonox-sdk"
+version = "0.2.3"
+description = "FastAPI observability SDK for Lumonox"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Lumonox maintainers" }]
+keywords = ["fastapi", "observability", "monitoring", "apm", "errors", "telemetry"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: FastAPI",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fastapi>=0.115.0",
+    "httpx>=0.27.0",
+    "psutil>=6.0.0",
+]
+
+# ``pip install "lumonox-sdk[stack]"`` pulls the API + bundled dashboard (PyPI: ``lumonox``) alongside this SDK.
+[project.optional-dependencies]
+stack = ["lumonox>=0.2.5"]
+
+[project.urls]
+Homepage = "https://github.com/sintimaski/lumonox"
+Repository = "https://github.com/sintimaski/lumonox"
+Documentation = "https://github.com/sintimaski/lumonox/blob/main/sdk/README.md"
+Changelog = "https://github.com/sintimaski/lumonox/blob/main/sdk/CHANGELOG.md"
+Issues = "https://github.com/sintimaski/lumonox/issues"
+
+[build-system]
+requires = ["hatchling>=1.26.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lumonox"]

lumonox_sdk-0.2.3/src/lumonox/__init__.py

@@ -0,0 +1,55 @@
+"""Lumonox SDK: FastAPI observability integration."""
+
+import os
+
+from lumonox._jobs import capture_background_job
+from lumonox._monitor import monitor
+from lumonox.widgets import (
+    BarChartWidget,
+    BaseDashboardWidget,
+    CardWidget,
+    DonutChartWidget,
+    HistogramWidget,
+    LineChartWidget,
+    ScatterPlotWidget,
+    StackedAreaWidget,
+)
+
+
+def lumonox(app: object, **kwargs: object) -> None:
+    """One-line FastAPI setup: remote ingest from env, or ``kwargs``.
+
+    Reads ``LUMONOX_MODE`` when ``mode`` is not passed: ``remote`` (default), or
+    ``off`` / ``false`` / ``0`` / ``no`` / ``none`` / ``disabled`` to skip instrumentation.
+    ``embedded`` is treated as ``remote`` (embedded mode was removed).
+    Sets ``environment`` to ``development`` when omitted (matches common dashboard filters).
+    Honors ``LUMONOX_SERVICE_NAME`` when ``service_name`` is not passed.
+    """
+    options = dict(kwargs)
+    if "mode" not in options:
+        raw = os.getenv("LUMONOX_MODE", "remote").strip().lower()
+        if raw in {"off", "false", "0", "no", "none", "disabled"}:
+            return
+        options["mode"] = "remote"
+    if "environment" not in options:
+        options["environment"] = "development"
+    if "service_name" not in options:
+        service_name = os.getenv("LUMONOX_SERVICE_NAME", "").strip()
+        if service_name:
+            options["service_name"] = service_name
+    monitor(app, **options)
+
+
+__all__ = [
+    "monitor",
+    "lumonox",
+    "capture_background_job",
+    "BaseDashboardWidget",
+    "CardWidget",
+    "LineChartWidget",
+    "BarChartWidget",
+    "DonutChartWidget",
+    "HistogramWidget",
+    "ScatterPlotWidget",
+    "StackedAreaWidget",
+]

lumonox_sdk-0.2.3/src/lumonox/_infrastructure.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from time import monotonic
+from typing import Any
+
+_LOG = logging.getLogger(__name__)
+
+psutil: Any
+try:
+    import psutil as _psutil
+except Exception:  # pragma: no cover - optional runtime dependency
+    psutil = None
+else:
+    psutil = _psutil
+
+
+@dataclass(slots=True)
+class InfrastructureSampler:
+    ttl_seconds: float = 2.0
+    _last_sample: dict[str, Any] = field(default_factory=dict)
+    _last_sampled_at: float = 0.0
+    _warned_sampling_error: bool = False
+
+    def sample(self) -> dict[str, Any]:
+        if psutil is None:
+            return {}
+        now = monotonic()
+        if self._last_sample and (now - self._last_sampled_at) < self.ttl_seconds:
+            return dict(self._last_sample)
+
+        try:
+            process = psutil.Process()
+            vm = psutil.virtual_memory()
+            disk = psutil.disk_usage("/")
+            disk_io = psutil.disk_io_counters()
+            net = psutil.net_io_counters()
+            payload: dict[str, Any] = {
+                "host_cpu_percent": float(psutil.cpu_percent(interval=None)),
+                "host_memory_used_percent": float(vm.percent),
+                "host_memory_total_bytes": float(vm.total),
+                "host_memory_used_bytes": float(vm.used),
+                "process_cpu_percent": float(process.cpu_percent(interval=None)),
+                "process_memory_percent": float(process.memory_percent()),
+                "process_memory_rss_bytes": float(process.memory_info().rss),
+                "disk_used_percent": float(disk.percent),
+                "disk_total_bytes": float(disk.total),
+                "disk_used_bytes": float(disk.used),
+                "disk_io_read_bytes": float(disk_io.read_bytes if disk_io is not None else 0.0),
+                "disk_io_write_bytes": float(disk_io.write_bytes if disk_io is not None else 0.0),
+                "network_bytes_sent": float(net.bytes_sent),
+                "network_bytes_recv": float(net.bytes_recv),
+            }
+        except Exception as exc:
+            if not self._warned_sampling_error:
+                _LOG.warning(
+                    "lumonox infrastructure sampling disabled for this process: %s",
+                    exc,
+                )
+                self._warned_sampling_error = True
+            return {}
+        self._last_sample = payload
+        self._last_sampled_at = now
+        return dict(payload)

lumonox_sdk-0.2.3/src/lumonox/_jobs.py

@@ -0,0 +1,58 @@
+"""Optional background job / cron outcome capture (non-blocking)."""
+
+from __future__ import annotations
+
+import traceback
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+
+def capture_background_job(
+    app: Any,
+    *,
+    name: str,
+    success: bool,
+    latency_ms: float = 0.0,
+    trigger: Literal["job", "cron"] = "job",
+    correlated_request_id: str | None = None,
+    exception: BaseException | None = None,
+) -> None:
+    """Record a completed background task as a ``type=job`` ingest row (silent if not configured).
+
+    Requires ``monitor()`` / ``lumonox()`` to have been applied on ``app`` so
+    ``app.state._lumonox_dispatcher`` exists. Never raises to the caller.
+    """
+    try:
+        dispatcher = getattr(app.state, "_lumonox_dispatcher", None)
+        config = getattr(app.state, "_lumonox_config", None)
+        if dispatcher is None or config is None:
+            return
+        raw_name = str(name or "").strip() or "background_task"
+        path = raw_name[:2048]
+        method = "CRON" if trigger == "cron" else "JOB"
+        ok = bool(success) and exception is None
+        status_code = 200 if ok else 500
+        payload: dict[str, Any] = {
+            "type": "job",
+            "timestamp": datetime.now(tz=UTC).isoformat(),
+            "service_name": str(getattr(config, "service_name", "api") or "api")[:120],
+            "environment": str(getattr(config, "environment", "production") or "production")[:120],
+            "method": method,
+            "path": path,
+            "status_code": status_code,
+            "latency_ms": max(0.0, float(latency_ms)),
+            "job_trigger": trigger,
+        }
+        if correlated_request_id and str(correlated_request_id).strip():
+            payload["correlated_request_id"] = str(correlated_request_id).strip()[:128]
+            payload["request_id"] = str(correlated_request_id).strip()[:128]
+        if exception is not None:
+            payload["exception_type"] = type(exception).__name__
+            msg = str(exception).strip()
+            if msg:
+                payload["exception_message"] = msg[:4000]
+            stack = traceback.format_exception(type(exception), exception, exception.__traceback__)
+            payload["stack_trace"] = "".join(stack)[-16_000:]
+        dispatcher.enqueue(payload)
+    except Exception:
+        return