Metadata-Version: 2.4
Name: watchforge-sdk
Version: 0.1.5
Summary: WatchForge Python SDK
Author-email: WatchForge <support@watchforge.io>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Dynamic: license-file

# WatchForge Python SDK (`watchforge-sdk`)

Python SDK for WatchForge — errors, traces, structured logs, releases, and cron monitors.

## Install

```bash
pip install watchforge-sdk
```

## Quick start

```python
from watchforge_sdk import register
import logging

register(
    endpoint="https://PUBLIC_KEY@dev.watchforges.com/PROJECT_ID",
    app_env="production",
    release="my-api@1.0.0",  # for Releases / crash-free
    traces_sample_rate=1.0,  # 100% of traces (0.0–1.0)
    enable_logs=True,        # structured logs (default True)
)

logging.info("hello")  # captured automatically when enable_logs + auto_capture_logging
```

## Feature matrix

| Feature | Supported | Notes |
| --- | --- | --- |
| **Errors** | Yes | Unhandled exceptions + `capture_exception` / `capture_message` |
| **Traces** | Yes | Integrations (e.g. Django) + `start_transaction`; sampled via `traces_sample_rate` |
| **Session Replay** | Not supported | Browser SDKs only |
| **Logs** | Yes | `enable_logs` + stdlib `logging` + `capture_log` |
| **Releases** | Yes | Set `release` at `register()`; view under **Releases** |
| **Cron monitors** | Yes | `capture_checkin` (`in_progress` → `ok` / `error`) |

## Errors

Unhandled exceptions are captured automatically. For handled errors:

```python
from watchforge_sdk import capture_exception, capture_message

try:
    process()
except Exception as e:
    capture_exception(e)

capture_message("payment processed", level="info")
```

## Traces

Set `traces_sample_rate` once at register (**0.0–1.0**). Prefer Django integration for automatic request traces.

```python
from watchforge_sdk import start_transaction, finish_transaction

txn = start_transaction("/api/orders", "Create Order", op="http.server")
span = txn.start_span("db.query", "INSERT orders")
span.finish()
finish_transaction("ok")
```

## Session Replay

**Not supported** in the Python SDK. Use `@watchforge/browser` for session replay.

## Logs

Leave `enable_logs=True` (default). With `auto_capture_logging=True`, stdlib `logging` is forwarded. Set `enable_logs=False` to disable.

```python
from watchforge_sdk import capture_log, flush_logs

capture_log("order created", level="info", attributes={"order_id": "123"})
flush_logs()
```

## Releases

Set `release` once at `register()` (e.g. `my-api@1.2.3`). Versions appear under **Releases** for the project.

## Cron monitors

Report scheduled job health with check-ins (`in_progress` → `ok` / `error`):

```python
from watchforge_sdk import capture_checkin

monitor_config = {
    "schedule": {"type": "crontab", "value": "0 * * * *"},
    "timezone": "UTC",
    "check_margin": 5,
    "max_runtime": 30,
}

check_in_id = capture_checkin(
    "nightly-job",
    status="in_progress",
    monitor_config=monitor_config,
)
# ... run job ...
capture_checkin("nightly-job", status="ok", check_in_id=check_in_id)
```

## Config options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `endpoint` / `dsn` | str | required | Project DSN |
| `app_env` | str | `"production"` | Environment name |
| `release` | str | `None` | Deploy version for Releases |
| `enable_logs` | bool | `True` | Gate structured logs |
| `auto_capture_logging` | bool | `True` | Capture stdlib logging |
| `traces_sample_rate` | float | `1.0` | Trace sample rate **0.0–1.0** |
| `integrations` | list | `None` | e.g. `[DjangoHandler()]` |

## License

MIT
