Skip to content

README.md

Latest commit

 

History

History
216 lines (159 loc) · 4.2 KB

README.md

File metadata and controls

216 lines (159 loc) · 4.2 KB

ErrorWatch Python SDK

Self-hosted error monitoring SDK for Python applications. Compatible with FastAPI, Flask, Django, Celery, and any Python application.

Installation

pip install errorwatch

# With framework extras
pip install errorwatch[fastapi]
pip install errorwatch[flask]
pip install errorwatch[django]
pip install errorwatch[celery]
pip install errorwatch[sqlalchemy]
pip install errorwatch[all]

Quick Start

import errorwatch

errorwatch.init(
    api_key="ew_live_your_api_key",
    endpoint="https://api.errorwatch.io",
    environment="production",
    release="1.0.0",
)

# Automatic capture via sys.excepthook — unhandled exceptions are sent automatically

# Manual capture
try:
    risky_operation()
except Exception as e:
    errorwatch.capture_exception(e)

# Capture a message
errorwatch.capture_message("Deployment completed", level="info")

Framework Integrations

FastAPI

from fastapi import FastAPI
import errorwatch
from errorwatch.integrations.fastapi import ErrorWatchMiddleware

app = FastAPI()

errorwatch.init(
    api_key="ew_live_xxx",
    endpoint="https://api.errorwatch.io",
)

app.add_middleware(ErrorWatchMiddleware)

Flask

from flask import Flask
import errorwatch
from errorwatch.integrations.flask import ErrorWatchFlask

app = Flask(__name__)

errorwatch.init(
    api_key="ew_live_xxx",
    endpoint="https://api.errorwatch.io",
)

ErrorWatchFlask(app)

Django

# settings.py
MIDDLEWARE = [
    "errorwatch.integrations.django.ErrorWatchMiddleware",
    # ... other middleware
]

# manage.py or wsgi.py (before Django starts)
import errorwatch

errorwatch.init(
    api_key="ew_live_xxx",
    endpoint="https://api.errorwatch.io",
)

Celery

import errorwatch
from errorwatch.integrations.celery import install

errorwatch.init(
    api_key="ew_live_xxx",
    endpoint="https://api.errorwatch.io",
)

install()  # Hooks into Celery signals

User Context

errorwatch.set_user({
    "id": "123",
    "email": "user@example.com",
    "username": "johndoe",
})

Breadcrumbs

errorwatch.add_breadcrumb(
    message="User clicked checkout",
    category="ui",
    data={"button": "checkout-btn"},
)

APM / Transactions

with errorwatch.start_transaction("process-order", op="task") as txn:
    with txn.start_child("db.query", description="SELECT * FROM orders") as span:
        orders = db.query("SELECT * FROM orders")
    
    with txn.start_child("http.client", description="POST /api/payment") as span:
        response = httpx.post("/api/payment")
        span.set_data("http.status_code", response.status_code)

SQLAlchemy Integration

from sqlalchemy import create_engine
from errorwatch.integrations.sqlalchemy import install

engine = create_engine("postgresql://...")
install(engine)  # Auto-traces all SQL queries

httpx Tracing

import httpx
from errorwatch.integrations.httpx_integration import install_hooks

client = httpx.Client()
install_hooks(client)  # Auto-traces outgoing HTTP requests

Logging Integration

import logging
from errorwatch.integrations.logging_handler import ErrorWatchHandler

handler = ErrorWatchHandler(level=logging.ERROR)
logging.getLogger().addHandler(handler)

Configuration

errorwatch.init(
    # Required
    api_key="ew_live_xxx",
    endpoint="https://api.errorwatch.io",
    
    # Optional
    environment="production",       # Default: "production"
    release="1.2.3",               # App version
    enabled=True,                   # Kill switch
    sample_rate=1.0,               # Error sampling (0.0-1.0)
    
    # Hooks
    before_send=lambda event: event,  # Filter/modify events, return None to drop
    
    # Transport
    transport={
        "timeout": 5.0,
        "retry_attempts": 2,
        "circuit_breaker_threshold": 5,
        "circuit_breaker_cooldown": 60.0,
    },
    
    # Breadcrumbs
    breadcrumbs={"enabled": True, "max_count": 100},
    
    # APM
    apm={"enabled": True, "sample_rate": 1.0},
    
    # Logs
    logs={"enabled": True, "level": "error"},
)

Requirements

  • Python >= 3.10
  • httpx >= 0.24.0

License

MIT