Metadata-Version: 2.4
Name: devlite
Version: 0.1.1
Summary: DevLite Python SDK — AI-powered observability with a 2-line integration. Automatic error grouping, source context, user impact tracking, and sensitive-data scrubbing built in.
License: MIT
Project-URL: Homepage, https://devlite.io
Project-URL: Repository, https://github.com/Ishimwe-Kevin/devlite-app
Keywords: observability,monitoring,apm,error-tracking,error-monitoring,logging,ai,devlite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: flask
Requires-Dist: flask>=2.0; extra == "flask"
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == "fastapi"
Provides-Extra: django
Requires-Dist: django>=4.0; extra == "django"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: flask>=2.0; extra == "test"
Requires-Dist: fastapi>=0.100; extra == "test"
Requires-Dist: django>=4.0; extra == "test"
Requires-Dist: httpx>=0.27; extra == "test"
Dynamic: license-file

# devlite — Python SDK

AI-powered observability for Python. Add two lines, get automatic request tracking, error capture, error grouping, source context, user tracking, and slow-endpoint detection — no config files, no manual instrumentation, **zero runtime dependencies**.

This is the Python counterpart of [`@devlite/nodejs`](https://www.npmjs.com/package/@devlite/nodejs) — both SDKs speak the same batch protocol to the [DevLite ingest API](https://github.com/Ishimwe-Kevin/devlite-app).

## Install

```bash
pip install devlite            # core (Flask/FastAPI/Django optional)
pip install "devlite[flask]"   # + Flask instrumentation
pip install "devlite[fastapi]" # + FastAPI instrumentation
pip install "devlite[django]"  # + Django instrumentation
```

## 60-second quickstart (Flask)

```python
from flask import Flask
import devlite

devlite.init(api_key="dl_live_xxxxx")

app = Flask(__name__)
devlite.instrument_flask(app)
```

That's it — every HTTP request, slow endpoint, and unhandled exception is now captured automatically, with:

- **Grouped errors** — the same bug occurring 1,000 times shows up as one issue, not 1,000
- **Real source code context** — the actual lines around the crash, read live from disk
- **Automatic sensitive-data scrubbing** — emails, tokens, passwords redacted before anything leaves your process
- **User impact tracking** — know exactly which users hit which bugs

Point `api_key`/`endpoint` at your own DevLite ingest instance (Supabase-backed) to start seeing data.

## Auto-instrumentation for every framework

One call per framework, with the same automatic request/slow-request/error/user tracking:

**FastAPI** (any Starlette app) — call right after creating the app:

```python
from fastapi import FastAPI
import devlite

devlite.init(api_key="dl_live_xxxxx")

app = FastAPI()
devlite.instrument_fastapi(app)   # before the server starts
```

**Django** — `instrument_django()` inserts `devlite._django.InstrumentDjangoMiddleware` at the top of your `MIDDLEWARE` setting:

```python
import devlite

devlite.init(api_key="dl_live_xxxxx")
devlite.instrument_django()
```

Or add the middleware manually (must be near the top, index 0 ideally):

```python
MIDDLEWARE = [
    "devlite._django.InstrumentDjangoMiddleware",
    ...
]
```

Any other framework (or plain WSGI/ASGI) still works through the manual API below.

## Manual capture API

```python
# Capture a handled error with extra context
devlite.capture_error(err, {"userId": "123", "action": "checkout"})
devlite.capture_error(err, {"fingerprint": "payment-timeout"})  # force grouping key

# Non-error event
devlite.capture_message("Payment retried after timeout", "warning")

# Custom metric — feeds forecasting/anomaly detection
devlite.report_metric("order.total", 42.5, unit="USD", tags={"region": "lagos"})

# Structured log line
devlite.capture_log("checkout completed", "info", {"orderId": "ord_123", "durationMs": 250})

# Trace a unit of work
span = devlite.start_span("checkout.process", {"trace_id": "abc"})
span.end("ok")  # "ok" | "error"

# Tell DevLite about a deployment (powers before/after performance views)
devlite.report_deployment(version="v2.1.3", commit_sha="a1b2c3d")

# Breadcrumbs attach to the next captured error, improving AI root-cause
devlite.add_breadcrumb({"type": "business_event", "note": "user started checkout"})

# Tag all subsequent events
devlite.set_tag("region", "lagos")
```

## User impact tracking

`set_user()` is scoped to the current request (via `contextvars`, so concurrent requests never leak each other's identity):

```python
# Flask
from flask import request

@app.before_request
def identify():
    devlite.set_user({"id": request.remote_addr, "email": request.headers.get("X-User-Email")})

# FastAPI — inside any endpoint
devlite.set_user({"id": "u-123", "email": "a@example.com"})

# Django — inside any view
def my_view(request):
    devlite.set_user({"id": request.user.id, "email": request.user.email})
```

## Configuration options

```python
devlite.init({
    "api_key": "dl_live_xxxxx",        # required
    "environment": "production",        # default: $DEVLITE_ENVIRONMENT or "development"
    "service_name": "payments-api",     # default: $DEVLITE_SERVICE_NAME or current folder
    "release": "v2.1.3",                # e.g. git sha, shown in deployment views
    "sample_rate": 1.0,                 # 0.0–1.0. Sampling is COHERENT: a sampled-out
                                        # request drops its errors/spans/logs/metrics together.
    "capture_body": False,              # capture (redacted) request headers — off by default
    "flush_interval_ms": 5000,          # how often batched events are sent
    "gzip": True,                       # compress request bodies (Content-Encoding: gzip)
    "debug": False,                     # log SDK internals
    "on_error": lambda err: print(err), # SDK-internal send failures
})
```

All of `api_key`, `service_name`, `release`, and `endpoint` can also be set via environment variables (`DEVLITE_API_KEY`, `DEVLITE_SERVICE_NAME`, `DEVLITE_RELEASE`, `DEVLITE_ENDPOINT`).

## Serverless / short-lived processes

Events are batched, so call `flush()` before your function returns:

```python
devlite.flush()
```

## Graceful shutdown

The SDK flushes remaining events on interpreter exit (`atexit`). If you manage shutdown yourself:

```python
devlite.close()
```

## What makes this competitive

- **Automatic error grouping** — the same underlying bug, however many times it fires, is fingerprinted and grouped into one issue, instead of flooding your dashboard with duplicates.
- **Source code context** — every captured error includes the actual lines of code around the crash, read live from disk, not just a bare stack trace.
- **Automatic sensitive-data scrubbing** — on by default. Emails, JWTs, bearer tokens, AWS keys, credit card numbers, and any field literally named `password`/`token`/`secret` are redacted before anything leaves your process.
- **Never blocks your app** — all sends are async (background thread), batched, and retried with backoff. If DevLite's backend is unreachable, your app keeps running.
- **Zero dependencies** — pure Python standard library.

## Development

```bash
pip install -e ".[flask,fastapi,django,test]"
python -m pytest
```

## License

MIT
