loggerai-sdk 0.1.0__tar.gz

loggerai_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Test and publish
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.8", "3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e . pytest fastapi httpx flask django sqlalchemy requests
+      - run: pytest -q
+
+  publish:
+    # A tag like v0.1.0 publishes that version to PyPI (trusted publishing: no token stored).
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

loggerai_sdk-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/

loggerai_sdk-0.1.0/LICENSE

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

loggerai_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: loggerai-sdk
+Version: 0.1.0
+Summary: LoggerAI for Python: performance monitoring, errors, logs and health checks for FastAPI, Django, Flask and Celery.
+Project-URL: Homepage, https://loggerai.uk
+Project-URL: Source, https://github.com/ehisakhile/loggerai-python
+Author-email: LoggerAI <dev@loggerai.uk>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apm,django,errors,fastapi,flask,logging,monitoring,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# LoggerAI for Python
+
+Performance monitoring, errors, logs and health checks for FastAPI,
+Starlette, Django, Flask and Celery, with AI that explains what went wrong.
+
+- **Every endpoint** timed under its route template (`/orders/{order_id}`):
+  p50/p95/p99, Apdex, status codes, slow and failed requests.
+- **What each request waits on**: database queries (SQLAlchemy and Django),
+  outgoing HTTP (`httpx`, `requests`), Redis.
+- **Exceptions**, grouped by cause, with stack traces that show your code first.
+- **Logs** at warning and above.
+- **Health checks** you define (database, cache, a queue).
+- **Background work** (Celery tasks, scripts) timed like requests.
+- **Browser sessions** recorded by LoggerAI's browser script link to the
+  server request each click caused (`traceparent`, `x-loggerai-session`).
+
+The package is `loggerai-sdk`; you import it as `loggerai`.
+
+Secrets (passwords, tokens, cookies, API keys, JWTs) are masked before
+anything leaves your server, request and response bodies are never sent, and
+users are counted by a one-way hash of their id. No dependencies; Python 3.8+.
+
+## Install
+
+```bash
+pip install loggerai-sdk
+```
+
+Get your project's **secret key** (`sk_live_...`) from LoggerAI → your
+project → **Connect**, and set it in the environment:
+
+```bash
+LOGGERAI_KEY=sk_live_...
+LOGGERAI_RELEASE=$GIT_SHA      # optional: "since release X"
+```
+
+Without a key nothing is recorded or sent, so local development stays quiet.
+
+### FastAPI / Starlette
+
+```python
+import loggerai
+from loggerai.asgi import LoggerAIMiddleware
+
+loggerai.init()
+app = FastAPI()
+app.add_middleware(LoggerAIMiddleware)
+```
+
+### Django
+
+```python
+# settings.py
+import loggerai
+loggerai.init()
+
+MIDDLEWARE = [
+    "loggerai.django.LoggerAIMiddleware",   # first
+    ...
+]
+```
+
+### Flask
+
+```python
+import loggerai, loggerai.flask
+
+loggerai.init()
+app = Flask(__name__)
+loggerai.flask.instrument(app)
+```
+
+### Celery
+
+```python
+import loggerai, loggerai.celery
+
+loggerai.init(service="worker")
+loggerai.celery.instrument()
+```
+
+### Any other WSGI app
+
+```python
+from loggerai.wsgi import LoggerAIMiddleware
+application = LoggerAIMiddleware(application)
+```
+
+## Health checks
+
+```python
+def database():
+    with engine.connect() as c:
+        c.execute(text("SELECT 1"))
+    return True               # or (False, "why")
+
+loggerai.init(health_checks={"database": database, "redis": lambda: r.ping()})
+```
+
+They run every minute in the background and show on the project's health
+page; alert on them from the dashboard.
+
+## More
+
+```python
+loggerai.set_user(request.user.id)          # only a one-way hash is sent
+
+with loggerai.measure("api.stripe.com", "POST"):   # calls it can't see itself
+    stripe.PaymentIntent.confirm(intent_id)
+
+with loggerai.track("job", "send_invoices"):       # scripts, cron jobs
+    send_invoices()
+
+try:
+    risky()
+except ValueError as e:
+    loggerai.capture_exception(e, order=order.id)  # handled, but worth seeing
+
+loggerai.flush()     # at the end of a short script or a serverless call
+```
+
+## Settings
+
+| Environment | `init()` | Default | |
+|---|---|---|---|
+| `LOGGERAI_KEY` | `key` | — | Secret key; off without it |
+| `LOGGERAI_SERVICE` | `service` | `app` | Name this process (`api`, `worker`) |
+| `LOGGERAI_ENVIRONMENT` | `environment` | `production` | Separates production from staging |
+| `LOGGERAI_RELEASE` | `release` | — | Version or git SHA |
+| `LOGGERAI_ENABLED` | `enabled` | `true` | Turn it off without removing the key |
+| | `logs_level` | `"WARNING"` | Lowest log level sent; `None` for no logs |
+| | `ignore_paths` | `/health`, `/up`, … | Paths not recorded |
+| | `capture_queries`, `capture_http`, `capture_redis` | `True` | |
+| | `flush_interval` | `5` | Seconds between batches |
+
+## How it sends
+
+Records are kept in memory and sent from a background thread every few
+seconds, gzipped, with a 2-second timeout. Requests never wait on LoggerAI.
+If it can't be reached, records are dropped instead of piling up. With
+gunicorn or uWSGI, each worker process sends its own batches.
+
+## Support
+
+dev@loggerai.uk · https://loggerai.uk

loggerai_sdk-0.1.0/README.md

@@ -0,0 +1,145 @@
+# LoggerAI for Python
+
+Performance monitoring, errors, logs and health checks for FastAPI,
+Starlette, Django, Flask and Celery, with AI that explains what went wrong.
+
+- **Every endpoint** timed under its route template (`/orders/{order_id}`):
+  p50/p95/p99, Apdex, status codes, slow and failed requests.
+- **What each request waits on**: database queries (SQLAlchemy and Django),
+  outgoing HTTP (`httpx`, `requests`), Redis.
+- **Exceptions**, grouped by cause, with stack traces that show your code first.
+- **Logs** at warning and above.
+- **Health checks** you define (database, cache, a queue).
+- **Background work** (Celery tasks, scripts) timed like requests.
+- **Browser sessions** recorded by LoggerAI's browser script link to the
+  server request each click caused (`traceparent`, `x-loggerai-session`).
+
+The package is `loggerai-sdk`; you import it as `loggerai`.
+
+Secrets (passwords, tokens, cookies, API keys, JWTs) are masked before
+anything leaves your server, request and response bodies are never sent, and
+users are counted by a one-way hash of their id. No dependencies; Python 3.8+.
+
+## Install
+
+```bash
+pip install loggerai-sdk
+```
+
+Get your project's **secret key** (`sk_live_...`) from LoggerAI → your
+project → **Connect**, and set it in the environment:
+
+```bash
+LOGGERAI_KEY=sk_live_...
+LOGGERAI_RELEASE=$GIT_SHA      # optional: "since release X"
+```
+
+Without a key nothing is recorded or sent, so local development stays quiet.
+
+### FastAPI / Starlette
+
+```python
+import loggerai
+from loggerai.asgi import LoggerAIMiddleware
+
+loggerai.init()
+app = FastAPI()
+app.add_middleware(LoggerAIMiddleware)
+```
+
+### Django
+
+```python
+# settings.py
+import loggerai
+loggerai.init()
+
+MIDDLEWARE = [
+    "loggerai.django.LoggerAIMiddleware",   # first
+    ...
+]
+```
+
+### Flask
+
+```python
+import loggerai, loggerai.flask
+
+loggerai.init()
+app = Flask(__name__)
+loggerai.flask.instrument(app)
+```
+
+### Celery
+
+```python
+import loggerai, loggerai.celery
+
+loggerai.init(service="worker")
+loggerai.celery.instrument()
+```
+
+### Any other WSGI app
+
+```python
+from loggerai.wsgi import LoggerAIMiddleware
+application = LoggerAIMiddleware(application)
+```
+
+## Health checks
+
+```python
+def database():
+    with engine.connect() as c:
+        c.execute(text("SELECT 1"))
+    return True               # or (False, "why")
+
+loggerai.init(health_checks={"database": database, "redis": lambda: r.ping()})
+```
+
+They run every minute in the background and show on the project's health
+page; alert on them from the dashboard.
+
+## More
+
+```python
+loggerai.set_user(request.user.id)          # only a one-way hash is sent
+
+with loggerai.measure("api.stripe.com", "POST"):   # calls it can't see itself
+    stripe.PaymentIntent.confirm(intent_id)
+
+with loggerai.track("job", "send_invoices"):       # scripts, cron jobs
+    send_invoices()
+
+try:
+    risky()
+except ValueError as e:
+    loggerai.capture_exception(e, order=order.id)  # handled, but worth seeing
+
+loggerai.flush()     # at the end of a short script or a serverless call
+```
+
+## Settings
+
+| Environment | `init()` | Default | |
+|---|---|---|---|
+| `LOGGERAI_KEY` | `key` | — | Secret key; off without it |
+| `LOGGERAI_SERVICE` | `service` | `app` | Name this process (`api`, `worker`) |
+| `LOGGERAI_ENVIRONMENT` | `environment` | `production` | Separates production from staging |
+| `LOGGERAI_RELEASE` | `release` | — | Version or git SHA |
+| `LOGGERAI_ENABLED` | `enabled` | `true` | Turn it off without removing the key |
+| | `logs_level` | `"WARNING"` | Lowest log level sent; `None` for no logs |
+| | `ignore_paths` | `/health`, `/up`, … | Paths not recorded |
+| | `capture_queries`, `capture_http`, `capture_redis` | `True` | |
+| | `flush_interval` | `5` | Seconds between batches |
+
+## How it sends
+
+Records are kept in memory and sent from a background thread every few
+seconds, gzipped, with a 2-second timeout. Requests never wait on LoggerAI.
+If it can't be reached, records are dropped instead of piling up. With
+gunicorn or uWSGI, each worker process sends its own batches.
+
+## Support
+
+dev@loggerai.uk · https://loggerai.uk

loggerai_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "loggerai-sdk"
+dynamic = ["version"]
+description = "LoggerAI for Python: performance monitoring, errors, logs and health checks for FastAPI, Django, Flask and Celery."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.8"
+authors = [{ name = "LoggerAI", email = "dev@loggerai.uk" }]
+keywords = ["monitoring", "apm", "observability", "fastapi", "django", "flask", "errors", "logging"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: Django",
+  "Framework :: FastAPI",
+  "Framework :: Flask",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://loggerai.uk"
+Source = "https://github.com/ehisakhile/loggerai-python"
+
+[tool.hatch.version]
+path = "src/loggerai/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/loggerai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

loggerai_sdk-0.1.0/src/loggerai/__init__.py

@@ -0,0 +1,122 @@
+"""
+LoggerAI for Python: performance monitoring, errors, logs and health checks
+for FastAPI, Starlette, Django, Flask and Celery.
+
+    import loggerai
+    loggerai.init()                      # reads LOGGERAI_KEY (sk_live_...)
+
+    # FastAPI / Starlette
+    from loggerai.asgi import LoggerAIMiddleware
+    app.add_middleware(LoggerAIMiddleware)
+
+Nothing is sent without a key, nothing ever raises into your app, and
+secrets are masked before anything leaves it.
+"""
+from __future__ import annotations
+
+import contextlib
+import time
+from typing import Any, Callable, Dict, Iterator, Optional
+
+from . import context
+from ._version import __version__
+from .client import Client, get_client, set_client
+
+__all__ = ["init", "capture_exception", "set_user", "set_route", "measure", "track", "flush", "health_checks", "Client", "__version__"]
+
+
+def init(key: Optional[str] = None, **options: Any) -> Client:
+    """Start LoggerAI. Every option also has an environment variable:
+    key (LOGGERAI_KEY), endpoint, service, environment, release, enabled.
+    Others: logs_level ("WARNING", or None for no logs), capture_queries,
+    capture_http, capture_redis, ignore_paths, health_checks={"database": fn},
+    flush_interval (seconds), timeout, root (the app's folder, for stack traces)."""
+    old = get_client()
+    if old is not None:
+        old.close(timeout=1.0)
+    client = Client(key, **options)
+    set_client(client)
+    if client.enabled:
+        from . import instrument
+        instrument.all_from(client)
+        if client.health_checks:
+            client.start()
+    return client
+
+
+def capture_exception(exc: Optional[BaseException] = None, **extra: Any) -> None:
+    """Report an exception you handled but still want to see."""
+    import sys
+    exc = exc or sys.exc_info()[1]
+    client = get_client()
+    if exc is not None and client is not None:
+        client.exception(exc, handled=True, extra=extra or None)
+
+
+def set_user(user_id: Any) -> None:
+    """Count the current request against a user. Only a one-way hash of the id is sent."""
+    unit, client = context.current.get(), get_client()
+    if unit is not None and client is not None:
+        unit.user = client.user_ref(user_id)
+
+
+def set_route(template: str) -> None:
+    """Name the current request yourself (a template like /orders/{id}, never a raw path)."""
+    unit = context.current.get()
+    if unit is not None:
+        unit.route = template
+
+
+@contextlib.contextmanager
+def measure(target: str, operation: str = "CALL") -> Iterator[None]:
+    """Time a call LoggerAI can't see on its own, e.g. an SDK with its own HTTP client:
+
+        with loggerai.measure("api.stripe.com", "POST"):
+            stripe.PaymentIntent.confirm(...)
+    """
+    t = time.perf_counter()
+    ok = False
+    try:
+        yield
+        ok = True
+    finally:
+        context.dependency(target, operation, (time.perf_counter() - t) * 1000, ok)
+
+
+@contextlib.contextmanager
+def track(kind: str, name: str) -> Iterator[context.Unit]:
+    """Time a unit of work outside a web request: a job, a scheduled task, a script.
+
+        with loggerai.track("job", "send_invoices"):
+            ...
+    """
+    client = get_client()
+    unit = context.Unit(kind if kind in ("job", "command", "http") else "job", "JOB" if kind != "command" else "CLI")
+    unit.route = name
+    token = context.current.set(unit)
+    status = 200
+    try:
+        yield unit
+    except Exception as e:
+        status = 500
+        if client is not None:
+            client.exception(e, status=500)
+        raise
+    finally:
+        context.current.reset(token)
+        if client is not None:
+            client.finish(unit, status)
+
+
+def flush(timeout: float = 5.0) -> bool:
+    """Send everything now (e.g. at the end of a script or a serverless call)."""
+    client = get_client()
+    return client.flush(timeout) if client is not None else True
+
+
+def health_checks(checks: Dict[str, Callable[[], Any]]) -> None:
+    """Add health checks after init: each returns True/False, or (ok, detail)."""
+    client = get_client()
+    if client is not None:
+        client.health_checks.update(checks)
+        client.start()

loggerai_sdk-0.1.0/src/loggerai/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

loggerai_sdk-0.1.0/src/loggerai/asgi.py

@@ -0,0 +1,60 @@
+"""ASGI middleware: FastAPI, Starlette, and any ASGI app.
+
+    from loggerai.asgi import LoggerAIMiddleware
+    app.add_middleware(LoggerAIMiddleware)
+"""
+from __future__ import annotations
+
+from . import context
+from .client import get_client
+
+
+def _route(scope) -> str | None:
+    route = scope.get("route")
+    if route is not None:
+        path = getattr(route, "path_format", None) or getattr(route, "path", None)
+        if path:
+            # Routes inside a mounted sub-app are relative to the mount.
+            mount = scope.get("app_root_path") or ""
+            return (mount.rstrip("/") + path) if mount and not path.startswith(mount) else path
+    endpoint = scope.get("endpoint")
+    app = scope.get("app")
+    if endpoint is not None and app is not None:  # older Starlette: find the route by its endpoint
+        for r in getattr(app, "routes", []) or []:
+            if getattr(r, "endpoint", None) is endpoint:
+                return getattr(r, "path_format", None) or getattr(r, "path", None)
+    return None
+
+
+class LoggerAIMiddleware:
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        client = get_client()
+        if scope["type"] != "http" or client is None or not client.enabled or client.ignored(scope.get("path", "")):
+            return await self.app(scope, receive, send)
+        headers = {k.decode("latin-1").lower(): v.decode("latin-1") for k, v in scope.get("headers") or []}
+        unit = context.Unit("http", scope.get("method", "GET"), context.trace_from(headers.get("traceparent")),
+                            context.session_from(headers.get("x-loggerai-session")))
+        token = context.current.set(unit)
+        status = 500
+
+        async def _send(message):
+            nonlocal status
+            if message["type"] == "http.response.start":
+                status = message["status"]
+            await send(message)
+
+        try:
+            await self.app(scope, receive, _send)
+        except BaseException as e:
+            unit.route = unit.route or _route(scope)
+            if isinstance(e, Exception):
+                client.exception(e, status=500)
+            status = 500
+            raise
+        finally:
+            unit.route = unit.route or _route(scope)
+            context.current.reset(token)
+            client.finish(unit, status)

loggerai_sdk-0.1.0/src/loggerai/celery.py

@@ -0,0 +1,44 @@
+"""Celery: every task timed like a request (kind "job"), failures reported.
+
+    import loggerai, loggerai.celery
+    loggerai.init()
+    loggerai.celery.instrument()
+"""
+from __future__ import annotations
+
+from . import context
+from .client import get_client
+
+_tokens = {}
+
+
+def instrument() -> None:
+    from celery import signals
+
+    @signals.task_prerun.connect(weak=False)
+    def _start(task_id=None, task=None, **kw):
+        client = get_client()
+        if client is None or not client.enabled:
+            return
+        unit = context.Unit("job", "JOB")
+        unit.route = getattr(task, "name", None) or "task"
+        _tokens[task_id] = (unit, context.current.set(unit))
+
+    @signals.task_failure.connect(weak=False)
+    def _failed(task_id=None, exception=None, **kw):
+        client = get_client()
+        if client is not None and exception is not None:
+            client.exception(exception, status=500)
+
+    @signals.task_postrun.connect(weak=False)
+    def _end(task_id=None, state=None, **kw):
+        got = _tokens.pop(task_id, None)
+        client = get_client()
+        if got is None or client is None:
+            return
+        unit, token = got
+        try:
+            context.current.reset(token)
+        except ValueError:
+            context.current.set(None)
+        client.finish(unit, 200 if state == "SUCCESS" else 500)