watchforge-sdk 0.1.1

WatchForge Python SDK

WatchForge Python SDK (watchforge-sdk)

Python SDK for WatchForge — errors, traces, structured logs, and releases. Aligned with @watchforge/browser (JavaScript) and the other WatchForge language SDKs.

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 (Sentry-style 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 / mobile client SDKs only
Logs	Yes	enable_logs + stdlib logging (auto_capture_logging) + capture_log
Releases	Yes	Set release at register(); view under Releases (project-scoped)

Errors

With default settings, 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 (Sentry-style 0.0–1.0). Unsampled traces are dropped and not sent.

Prefer framework integrations (e.g. Django) so request traces are created automatically when the sample rate is > 0. Manual instrumentation:

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 (or other client SDKs) for session replay.

Logs

Like Sentry’s enableLogs: leave enable_logs=True (default). With auto_capture_logging=True, messages from Python’s logging module are sent automatically. You can also call capture_log directly. Set enable_logs=False to disable both auto capture and capture_log.

import logging
from watchforge_sdk import capture_log, capture_api_log, flush_logs

logging.info("user signed in")  # auto-captured

capture_log("order created", level="info", attributes={"order_id": "123"})
capture_api_log("GET /orders", attributes={"status": 200})
flush_logs()

Releases

Set release once at register() (e.g. my-api@1.2.3). Errors and traces tagged with that version appear under Releases for the project (sidebar → Releases). Omit release if you do not need release tracking.

Config options

Option	Type	Default	Description
endpoint / dsn	str	required	Project DSN
app_env / environment	str	"production"	Environment name
release	str	None	Deploy version for Releases / crash-free (e.g. my-api@1.2.3)
auto_capture_exceptions	bool	True	Capture unhandled exceptions
enable_logs	bool	True	Gate structured logs (Sentry-style). When False, capture_log is a no-op and auto logging is skipped
auto_capture_logging	bool	True	Capture stdlib logging messages (requires enable_logs=True)
logging_level	int	logging.INFO	Minimum level for auto log capture
debug	bool	False	Verbose SDK logging
integrations	list	None	e.g. [DjangoHandler()] for request traces
traces_sample_rate	float	1.0	Fraction of traces to send (0.0–1.0). 1.0 = 100%, 0.1 = 10%, 0.0 = off. Values > 1 are treated as percent (100 → 1.0).

Cron monitors

from watchforge_sdk import capture_checkin

check_in_id = capture_checkin("nightly-job", status="in_progress", monitor_config={...})
capture_checkin("nightly-job", status="ok", check_in_id=check_in_id)

License

MIT