Skip to main content

watchdock-errors

Python SDK for application-level error tracking on the Watchdock platform.

Installation

pip install watchdock-errors

With framework extras:

pip install "watchdock-errors[django]"
pip install "watchdock-errors[fastapi]"
pip install "watchdock-errors[celery]"

Quickstart

import watchdock_errors

watchdock_errors.init(
    api_key="wdk_xxx",
    environment="production",
    release="1.0.0",
)

Django

# settings.py
MIDDLEWARE = [
    ...
    "watchdock_errors.integrations.django.DjangoErrorMiddleware",
]

Or via INSTALLED_APPS for automatic registration:

INSTALLED_APPS = [
    ...
    "watchdock_errors.integrations.django",
]

FastAPI

from watchdock_errors.integrations.fastapi import setup_watchdock

setup_watchdock(app)

Celery

from celery import Celery
from watchdock_errors.integrations.celery import register

app = Celery("myproject")
app.config_from_object("django.conf:settings", namespace="CELERY")
app.autodiscover_tasks()

register(app)

Call register(app) once, after autodiscover_tasks(). It reports, automatically:

  • Task registry — every registered task (and, for periodic tasks, their beat schedule), once per worker on startup.
  • Failures, retries, and revocations — via task_failure, task_retry, and task_revoked. Successful runs are not reported.
  • Heartbeats for periodic tasks — a lightweight ping on every run of a beat-scheduled task, so Watchdock can flag one that's gone silent. Non-periodic tasks are never pinged.

watchdock_errors.init() must be called before these signals fire — if you're on Django, a worker_process_init handler that calls init() covers every forked worker process.

Manual capture

# Capture the current exception
try:
    process_payment()
except Exception:
    watchdock_errors.capture_exception()

# Capture a specific exception
watchdock_errors.capture_exception(exc)

# Capture a message
watchdock_errors.capture_message("Stripe webhook signature invalid")

# Capture a message with a custom level
watchdock_errors.capture_message("Queue depth high", level="warning")

Event levels

Every event carries a level. Exceptions default to "error"; messages default to "info" unless you pass level explicitly to capture_message.

Correlating with nginx requests

If your app is behind nginx and you've added $request_id to your access log format (see the nginx log collection docs) and forwarded it to your app via proxy_set_header X-Request-Id $request_id;, this SDK automatically reads that header off every captured request and attaches it as trace_id — no code changes needed. This lets WatchDock link a failed request in your nginx access logs directly to the exception it produced.

You can also pass trace_id explicitly, which takes priority over the auto-extracted value:

watchdock_errors.capture_exception(exc, trace_id=my_trace_id)
watchdock_errors.capture_message("Queue depth high", level="warning", trace_id=my_trace_id)

SDK initialization

When init() is called, the SDK sends a one-time, fire-and-forget ping to the platform (with the SDK version and environment) to register that it started up. This never blocks application startup and any failure is silently ignored.

PII scrubbing

By default, Authorization, Cookie, Set-Cookie, and X-Api-Key headers are stripped, the request body is not sent, and sensitive-looking query-param values (names containing token, secret, password, auth, key, session, credential, otp, pin, ssn, etc.) are redacted in both query_params and the captured url itself. Set send_pii=True to disable scrubbing.

Use the before_send hook for custom scrubbing:

def scrub(event):
    event["request"]["headers"].pop("X-Internal-Token", None)
    return event  # return None to drop the event entirely

watchdock_errors.init(api_key="wdk_xxx", before_send=scrub)

Metadata

Release files for watchdock-errors 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for watchdock-errors 0.5.1
File Size Uploaded Provenance Actions
watchdock_errors-0.5.1.tar.gz 18.3 kB Without provenance Details for watchdock_errors-0.5.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for watchdock-errors 0.5.1
File Interpreter ABI Platform Actions
watchdock_errors-0.5.1-py3-none-any.whl Python 3 none any Details for watchdock_errors-0.5.1-py3-none-any.whl

Total release size: 35.1 kB

Release files / watchdock_errors-0.5.1.tar.gz

Download URL watchdock_errors-0.5.1.tar.gz
Size 18.3 kB
Tags Source
SHA-256 checksum
How to use checksums
536709d79ee6c93bff5ca135875fd90d4174a49e08f0c2f50c7523d09732fcf5
BLAKE2b-256 checksum
How to use checksums
7b413e270660196d06af73ce506c9e65d0f8a66470763f287e1ac542e31302be
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / watchdock_errors-0.5.1-py3-none-any.whl

Download URL watchdock_errors-0.5.1-py3-none-any.whl
Size 16.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
923dc71942024c29dca29b198b865ced96d33404aae7525875ab7c7f63407f32
BLAKE2b-256 checksum
How to use checksums
32510cc6a0a0a96bc7646b2b8714139758a0eeb5302099d322d7ab50376c2b08
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for watchdock-errors 0.5.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page