allstak 0.1.2__tar.gz

allstak-0.1.2/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.pyo
+dist/
+build/
+*.egg-info/
+.eggs/
+.venv/
+venv/
+.env
+*.pyc

allstak-0.1.2/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+All notable changes to the AllStak Python SDK.
+This project follows [Semantic Versioning](https://semver.org/).
+
+## 0.1.2 — 2026-05-18
+
+### Fixed
+- **`capture_exception` always returned `None`** (critical functional bug). The
+  client unconditionally raised `AttributeError` on every capture because it
+  referenced `self.config` instead of `self._config` when merging release tags.
+  The exception was caught and swallowed silently, so the user-visible symptom
+  was just `None` return values and no events on the wire. Fix:
+  `src/allstak/client.py:235,288`.
+
+### Added
+- **`AllStak.Sanitizer`** (`src/allstak/sanitize.py`) — recursive scrubber for
+  the full event surface (user, metadata, breadcrumbs.data, contexts, request,
+  response). 25-term canonical denylist; `[REDACTED]` substitution; pure (no
+  caller mutation); cycle-safe via identity set.
+- Sanitizer wired into the wire-bound code path
+  (`src/allstak/modules/errors.py:_send`) so every event POST is scrubbed
+  before transport. Live canary `should_not_leak_python` planted in
+  `password` / `authorization` / `cookie` / `Bearer` / `credit_card` / `ssn` /
+  nested-token fields — verified `leak_pos = 0` across `metadata`,
+  `stack_trace`, `breadcrumbs`, and `message` in production ClickHouse
+  (event `f55a4839-357c-4aaa-a353-f4df4d6ff542`).
+- `tests/test_sanitize.py` — denylist, recursion, cycle, mutation tests.
+
+## 0.2.0 — 2026-04-11
+
+First production-ready release after a full real-world validation pass against a
+FastAPI + SQLAlchemy + SQLite application driving real authentication, CRUD,
+logs, outbound HTTP, cron jobs, and real exceptions — all verified end-to-end
+in the AllStak dashboard.
+
+### Highlights
+
+- **First-class FastAPI / Starlette integration** (`allstak.integrations.fastapi`)
+  — a single line (`AllStakFastAPI(app)`) captures inbound HTTP requests,
+  per-request trace IDs, unhandled exceptions, request context (method / path /
+  host / status / user-agent), and links every captured error to the owning
+  trace.
+- **SQLAlchemy integration** (`allstak.integrations.sqlalchemy.install`) —
+  hooks into SQLAlchemy's `before_cursor_execute` / `after_cursor_execute` /
+  `handle_error` events to record every ORM and Core query with real
+  timings, row counts, dialect detection, and error status. No monkey-patching.
+- **`RequestContext`** is now a first-class part of the error payload so the
+  dashboard can show the exact HTTP method / path / host / status on every
+  captured exception.
+- **`trace_id` is attached to errors automatically** (not just via metadata),
+  so the "Linked Traces" panel in the dashboard works out of the box.
+
+### Added
+
+- `allstak/integrations/fastapi.py` — FastAPI / Starlette ASGI middleware and
+  convenience wrapper, plus a new `fastapi` optional-dependency group.
+- `allstak/integrations/sqlalchemy.py` — SQLAlchemy event-based DB
+  instrumentation with a `sqlalchemy` optional-dependency group.
+- `allstak.RequestContext` — new dataclass exported at the package root.
+- `allstak.http.track_outbound(...)` now yields a recorder object so callers can
+  attach the real response status and body size (`call.set_response(status, size)`).
+- Extensive production-grade PyPI classifiers, URLs (homepage, docs, repo,
+  issues, changelog), and an `all` extra that installs every optional
+  integration.
+
+### Changed
+
+- **SDK version bumped from `0.1.0` → `0.2.0`.** New features + new public
+  API surface (`RequestContext`, FastAPI / SQLAlchemy integrations,
+  `track_outbound` recorder) justify a minor bump under semver: no breaking
+  changes for existing code, but meaningful new functionality.
+- `allstak.cron.job(...)` is now a **safe no-op context manager** when the SDK
+  is not initialized — previously it returned a plain function and broke
+  the documented `with allstak.cron.job("slug"):` idiom for uninitialized apps.
+- `sqlite3` auto-instrumentation now uses a `Connection` factory subclass
+  instead of trying to reassign `sqlite3.Cursor.execute` (which raises `TypeError`
+  on a built-in type). Standalone `sqlite3` usage is now actually captured.
+- The FastAPI middleware populates `scope["state"]` if missing so auth
+  dependencies can safely set `request.state.user` for error correlation.
+- `examples/basic_usage.py` now reads `ALLSTAK_API_KEY` from the environment
+  and aborts cleanly if it is missing, instead of shipping a hard-coded key.
+
+### Fixed
+
+- `HttpMonitorModule.track_outbound` no longer records every outbound call as
+  `status_code=0`. The context manager now yields a recorder that carries the
+  real status and size, and automatically tags the request with the exception
+  class name on failure.
+- Unhandled exceptions from FastAPI route handlers are now captured
+  automatically with full request context, stack trace, trace ID, and user
+  context — previously you had to call `allstak.capture_exception` manually.
+- Error events now include the current `trace_id` as a proper top-level field,
+  so the dashboard's Linked Traces panel resolves immediately.
+
+### What's new for Python users
+
+- If you use FastAPI:
+  ```python
+  from fastapi import FastAPI
+  import allstak
+  from allstak.integrations.fastapi import AllStakFastAPI
+
+  allstak.init(api_key="ask_live_...")
+  app = FastAPI()
+  AllStakFastAPI(app, service="my-api")
+  ```
+  That is the whole setup. Every request, every exception, and every trace are
+  captured automatically.
+- If you use SQLAlchemy (with any dialect — Postgres, MySQL, SQLite, etc.):
+  ```python
+  from sqlalchemy import create_engine
+  from allstak.integrations.sqlalchemy import install as install_sqlalchemy
+
+  engine = create_engine("postgresql://...")
+  install_sqlalchemy(engine)
+  ```
+- Cron monitoring still works exactly as before, but you can now safely use
+  `with allstak.cron.job("slug"):` even from scripts that might run without
+  the SDK initialized (tests, dry-runs, etc.).
+
+### Breaking changes
+
+None. `0.1.0` code keeps working as-is.
+
+---
+
+## 0.1.0 — 2026-03-28
+
+Initial beta release. Error capture, logs, HTTP monitoring, distributed
+tracing, cron heartbeats, basic Django & Flask integrations, and transport
+with retry/backoff + 401 disable.

allstak-0.1.2/LICENSE

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

allstak-0.1.2/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: allstak
+Version: 0.1.2
+Summary: Official Python SDK for AllStak — error tracking, structured logs, HTTP + DB monitoring, distributed tracing, and cron monitoring with first-class FastAPI, Django and Flask support
+Project-URL: Homepage, https://allstak.sa
+Project-URL: Documentation, https://allstak.sa/docs/sdks/python
+Project-URL: Repository, https://github.com/AllStak/allstak-python
+Project-URL: Issues, https://github.com/AllStak/allstak-python/issues
+Project-URL: Changelog, https://github.com/AllStak/allstak-python/blob/develop/CHANGELOG.md
+Author-email: AllStak <sdk@allstak.sa>
+Maintainer-email: AllStak <sdk@allstak.sa>
+License: MIT
+License-File: LICENSE
+Keywords: apm,django,error-tracking,fastapi,flask,logging,monitoring,observability,sqlalchemy,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Bug Tracking
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: all
+Requires-Dist: django>=3.2; extra == 'all'
+Requires-Dist: flask>=2.0; extra == 'all'
+Requires-Dist: sqlalchemy>=1.4; extra == 'all'
+Requires-Dist: starlette>=0.27; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: starlette>=0.27; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=1.4; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# allstak
+
+AllStak SDK for Python, Django, Flask, FastAPI, and plain services. Captures exceptions, logs, inbound and outbound HTTP requests, spans, database telemetry, and cron heartbeats.
+
+## Install
+
+> **Not yet on PyPI.** `pip install allstak` is reserved but does not
+> resolve a published artifact yet. Until first publish lands (tracked
+> in [`docs/devops/sdk-python-dotnet-first-publish.md`](https://github.com/AllStak/allstak/blob/dev/docs/devops/sdk-python-dotnet-first-publish.md)
+> in the platform monorepo), install directly from source:
+>
+> ```bash
+> pip install "git+https://github.com/AllStak/allstak-python.git@develop"
+> ```
+>
+> Once `0.1.x` ships on PyPI, the canonical install becomes:
+>
+> ```bash
+> pip install allstak
+> ```
+
+## Setup
+
+```python
+import os
+import allstak
+
+allstak.init(
+    api_key=os.getenv("ALLSTAK_API_KEY"),
+    environment=os.getenv("APP_ENV", "production"),
+    release=os.getenv("ALLSTAK_RELEASE"),
+)
+
+allstak.log.info("worker started")
+allstak.capture_exception(RuntimeError("checkout failed"))
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI
+from allstak.integrations.fastapi import AllStakFastAPI
+
+app = FastAPI()
+AllStakFastAPI(app, service="checkout-api")
+```
+
+## Flask
+
+```python
+from flask import Flask
+from allstak.integrations.flask import AllStakFlask
+
+app = Flask(__name__)
+AllStakFlask(app)
+```
+
+## Django
+
+Add the middleware:
+
+```python
+MIDDLEWARE = [
+    "allstak.integrations.django.AllStakDjangoMiddleware",
+    *MIDDLEWARE,
+]
+```
+
+## Spans
+
+```python
+with allstak.start_span("checkout.authorize", tags={"provider": "payments"}):
+    authorize_payment()
+```
+
+## Configuration
+
+| Option | Description |
+| --- | --- |
+| `api_key` | Project API key. |
+| `environment` | Deployment environment. |
+| `release` | App version or commit SHA. |
+| `flush_interval_ms` | Background flush interval. |
+| `buffer_size` | Max buffered events. |
+
+## Privacy
+
+The SDK redacts common sensitive headers and fields. Avoid putting secrets in custom metadata.
+
+## Troubleshooting
+
+- No events: confirm `ALLSTAK_API_KEY` is set before `allstak.init(...)`.
+- Missing request telemetry: register the framework integration during app startup.
+- Short-lived script: call `allstak.get_client().flush()` before exit when a client is initialized.
+
+## Contributing and Support
+
+- Report bugs with the GitHub bug report template: https://github.com/AllStak/allstak-python/issues/new/choose
+- Open pull requests using the checklist in [CONTRIBUTING.md](CONTRIBUTING.md).
+- Report security vulnerabilities privately through [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT

allstak-0.1.2/README.md

@@ -0,0 +1,104 @@
+# allstak
+
+AllStak SDK for Python, Django, Flask, FastAPI, and plain services. Captures exceptions, logs, inbound and outbound HTTP requests, spans, database telemetry, and cron heartbeats.
+
+## Install
+
+> **Not yet on PyPI.** `pip install allstak` is reserved but does not
+> resolve a published artifact yet. Until first publish lands (tracked
+> in [`docs/devops/sdk-python-dotnet-first-publish.md`](https://github.com/AllStak/allstak/blob/dev/docs/devops/sdk-python-dotnet-first-publish.md)
+> in the platform monorepo), install directly from source:
+>
+> ```bash
+> pip install "git+https://github.com/AllStak/allstak-python.git@develop"
+> ```
+>
+> Once `0.1.x` ships on PyPI, the canonical install becomes:
+>
+> ```bash
+> pip install allstak
+> ```
+
+## Setup
+
+```python
+import os
+import allstak
+
+allstak.init(
+    api_key=os.getenv("ALLSTAK_API_KEY"),
+    environment=os.getenv("APP_ENV", "production"),
+    release=os.getenv("ALLSTAK_RELEASE"),
+)
+
+allstak.log.info("worker started")
+allstak.capture_exception(RuntimeError("checkout failed"))
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI
+from allstak.integrations.fastapi import AllStakFastAPI
+
+app = FastAPI()
+AllStakFastAPI(app, service="checkout-api")
+```
+
+## Flask
+
+```python
+from flask import Flask
+from allstak.integrations.flask import AllStakFlask
+
+app = Flask(__name__)
+AllStakFlask(app)
+```
+
+## Django
+
+Add the middleware:
+
+```python
+MIDDLEWARE = [
+    "allstak.integrations.django.AllStakDjangoMiddleware",
+    *MIDDLEWARE,
+]
+```
+
+## Spans
+
+```python
+with allstak.start_span("checkout.authorize", tags={"provider": "payments"}):
+    authorize_payment()
+```
+
+## Configuration
+
+| Option | Description |
+| --- | --- |
+| `api_key` | Project API key. |
+| `environment` | Deployment environment. |
+| `release` | App version or commit SHA. |
+| `flush_interval_ms` | Background flush interval. |
+| `buffer_size` | Max buffered events. |
+
+## Privacy
+
+The SDK redacts common sensitive headers and fields. Avoid putting secrets in custom metadata.
+
+## Troubleshooting
+
+- No events: confirm `ALLSTAK_API_KEY` is set before `allstak.init(...)`.
+- Missing request telemetry: register the framework integration during app startup.
+- Short-lived script: call `allstak.get_client().flush()` before exit when a client is initialized.
+
+## Contributing and Support
+
+- Report bugs with the GitHub bug report template: https://github.com/AllStak/allstak-python/issues/new/choose
+- Open pull requests using the checklist in [CONTRIBUTING.md](CONTRIBUTING.md).
+- Report security vulnerabilities privately through [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT

allstak-0.1.2/examples/basic_usage.py

@@ -0,0 +1,137 @@
+"""
+Basic usage example — demonstrates core AllStak SDK features.
+
+Run with:
+    cd allstak-python
+    pip install -e ".[dev]"
+    python examples/basic_usage.py
+"""
+
+import os
+import sys
+import time
+
+import allstak
+
+# ---------------------------------------------------------------------------
+# 1. Initialize the SDK
+#
+# Set ALLSTAK_API_KEY (and optionally ALLSTAK_HOST) in your environment
+# before running this example. Never commit real API keys to source control.
+# ---------------------------------------------------------------------------
+
+api_key = os.environ.get("ALLSTAK_API_KEY")
+if not api_key:
+    sys.stderr.write("ALLSTAK_API_KEY is not set — aborting example.\n")
+    sys.exit(1)
+
+allstak.init(
+    api_key=api_key,
+    host=os.environ.get("ALLSTAK_HOST", "https://api.allstak.sa"),
+    environment=os.environ.get("ALLSTAK_ENVIRONMENT", "development"),
+    release=os.environ.get("ALLSTAK_RELEASE", "0.2.0"),
+    debug=bool(os.environ.get("ALLSTAK_DEBUG")),
+)
+print("✓ AllStak SDK initialized")
+
+# ---------------------------------------------------------------------------
+# 2. Set user context
+# ---------------------------------------------------------------------------
+
+allstak.set_user(user_id="usr-demo-001", email="demo@allstak.dev")
+print("✓ User context set")
+
+# ---------------------------------------------------------------------------
+# 3. Capture an exception
+# ---------------------------------------------------------------------------
+
+try:
+    result = 1 / 0
+except ZeroDivisionError as e:
+    event_id = allstak.capture_exception(
+        e,
+        metadata={
+            "source": "basic_usage_example",
+            "operation": "demo_division",
+        }
+    )
+    print(f"✓ Exception captured → event ID: {event_id}")
+
+# ---------------------------------------------------------------------------
+# 4. Capture an error by name (without exception object)
+# ---------------------------------------------------------------------------
+
+event_id = allstak.capture_error(
+    exception_class="ExternalServiceError",
+    message="Payment gateway timed out after 30s",
+    level="error",
+    metadata={
+        "gateway": "stripe",
+        "timeout_ms": 30000,
+    }
+)
+print(f"✓ Error captured → event ID: {event_id}")
+
+# ---------------------------------------------------------------------------
+# 5. Log messages
+# ---------------------------------------------------------------------------
+
+allstak.log.info("Application started", service="demo-app")
+allstak.log.warn(
+    "Slow query detected",
+    service="db-service",
+    metadata={"query_ms": 4200, "table": "orders"},
+)
+allstak.log.error(
+    "Failed to send email",
+    service="notifications",
+    metadata={"recipient": "user@example.com", "attempt": 3},
+)
+print("✓ Log messages queued")
+
+# ---------------------------------------------------------------------------
+# 6. Record HTTP requests
+# ---------------------------------------------------------------------------
+
+allstak.http.record(
+    direction="outbound",
+    method="POST",
+    host="payments.stripe.com",
+    path="/v1/charges",
+    status_code=200,
+    duration_ms=320,
+    request_size=256,
+    response_size=1024,
+)
+
+allstak.http.record(
+    direction="inbound",
+    method="GET",
+    host="api.myapp.com",
+    path="/api/users/me",
+    status_code=200,
+    duration_ms=18,
+)
+print("✓ HTTP requests recorded")
+
+# ---------------------------------------------------------------------------
+# 7. Session replay (server-side events)
+# ---------------------------------------------------------------------------
+
+import uuid
+session_id = str(uuid.uuid4())
+
+with allstak.replay.start_session(session_id=session_id) as session:
+    session.record("navigation", {"from": "/home", "to": "/dashboard"})
+    session.record("api_call", {"endpoint": "/api/users", "method": "GET"})
+    print(f"✓ Replay session {session.session_id[:8]}... recorded")
+
+# ---------------------------------------------------------------------------
+# 8. Flush everything
+# ---------------------------------------------------------------------------
+
+print("Flushing all buffers...")
+allstak.flush()
+time.sleep(0.5)  # give background workers time to complete
+print("✓ All events flushed")
+print("\nDone! Check http://localhost:3000/overview for results.")