Metadata-Version: 2.4
Name: runtimescope
Version: 0.10.11
Summary: RuntimeScope SDK for Python — runtime profiling and telemetry for Django, Flask, FastAPI, and any Python app
Author: RuntimeScope
License: MIT
Project-URL: Homepage, https://github.com/edwinlov3tt/runtimescope
Project-URL: Documentation, https://github.com/edwinlov3tt/runtimescope#readme
Project-URL: Repository, https://github.com/edwinlov3tt/runtimescope
Project-URL: Issues, https://github.com/edwinlov3tt/runtimescope/issues
Keywords: runtime,profiler,telemetry,observability,django,flask,fastapi,sentry-alternative
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: django
Requires-Dist: django>=3.2; extra == "django"
Provides-Extra: flask
Requires-Dist: flask>=2.0; extra == "flask"
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == "fastapi"
Requires-Dist: starlette>=0.27; extra == "fastapi"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"

# runtimescope (Python)

Python SDK for [RuntimeScope](https://github.com/edwinlov3tt/runtimescope) — runtime profiling and telemetry for Django, Flask, FastAPI, and any Python app.

```bash
pip install runtimescope
```

Zero required dependencies — the SDK uses only the Python standard library. Framework integrations (Django / Flask / FastAPI) are opt-in.

## Quick Start

```python
from runtimescope import RuntimeScope

RuntimeScope.connect(dsn="runtimescope://proj_xxx@localhost:6768/my-app")
# or set RUNTIMESCOPE_DSN in your environment and call with no args:
RuntimeScope.connect()

RuntimeScope.track("user_signed_up", {"plan": "pro"})
RuntimeScope.add_breadcrumb("task started", {"task_id": 42})
```

When `RUNTIMESCOPE_DSN` is not set, the SDK is **completely inert** — no connection attempts, no patching, zero overhead. Safe to ship to production.

## Framework Integrations

### Django

```python
# settings.py
MIDDLEWARE = [
    "runtimescope.integrations.django.RuntimeScopeMiddleware",
    # ...
]

# Optional: set DSN via Django settings (otherwise uses RUNTIMESCOPE_DSN env var)
RUNTIMESCOPE_DSN = "runtimescope://proj_xxx@localhost:6768/my-django-app"
```

### Flask

```python
from flask import Flask
from runtimescope.integrations.flask import init_app

app = Flask(__name__)
init_app(app)  # reads RUNTIMESCOPE_DSN from env
```

### FastAPI

```python
from fastapi import FastAPI
from runtimescope.integrations.fastapi import RuntimeScopeMiddleware

app = FastAPI()
app.add_middleware(RuntimeScopeMiddleware)
```

## What Gets Captured

| Capture | Default | How |
|---------|---------|-----|
| Every HTTP request | ✅ via middleware | method, URL, status, duration |
| Uncaught exceptions | ✅ | `sys.excepthook` hook |
| `logging.WARNING+` | ✅ | Python `logging` handler |
| Custom events | Manual | `RuntimeScope.track(name, properties)` |
| Breadcrumbs | Manual | `RuntimeScope.add_breadcrumb(msg, data)` |
| Manual exception | Manual | `RuntimeScope.capture_exception(exc)` |

You can disable the auto-captures via `connect()` kwargs:

```python
RuntimeScope.connect(
    dsn="...",
    capture_errors=False,    # don't install sys.excepthook
    capture_logging=False,   # don't hook into `logging`
)
```

## DSN Format

Same as every other RuntimeScope SDK:

```
runtimescope://proj_xxx@host:6768/app-name
runtimescopes://proj_xxx@runtimescope.example.com/app-name   # TLS
```

The HTTP port is canonical; the WebSocket port is derived as `http_port - 1`.

## Auth Tokens

Pass `auth_token="..."` to `connect()` or set `RUNTIMESCOPE_AUTH_TOKEN` in the environment. The token is sent as a Bearer header on every POST.

## License

MIT
