watchforge-sdk 0.1.2

WatchForge Python SDK

WatchForge Python SDK (watchforge-sdk)

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

Install

pip install watchforge-sdk

Quick start

from watchforge_sdk import register
import logging

register(
    endpoint="https://[e-mail]/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:

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.

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.

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):

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