theseeker-status

Python SDK for sending signed status events to TheSeeker ingest.

Install

pip install theseeker-status

Usage

import os

from theseeker_status import RESULT_OK, create_status_client

status = create_status_client(
    key_id=os.environ["THESEEKER_INGEST_KEY_ID"],
    secret=os.environ["THESEEKER_INGEST_SECRET"],
    endpoint="https://ingest.theseeker.io",
    slug="homepage",
)

status.report(
    RESULT_OK,
    latency_ms=123,
    message="homepage responded normally",
    metrics={"dnsMs": 12, "tlsMs": 30},
)

Send project feedback with the same client:

status.send_feedback(
    uid="user-123",
    content="Search results are slow.",
    fields={"plan": "pro"},
    extra={"screen": "search"},
)

When feedback_endpoint is omitted, the validated /v1/events endpoint is changed to /v1/feedback. An explicit feedback_endpoint must be an absolute HTTP(S) URL with /v1/feedback (or no path) and no query or fragment.

endpoint can be either the full events URL (https://ingest.theseeker.io/v1/events) or the base URL (https://ingest.theseeker.io). Base URLs are sent to /v1/events automatically.

If a client-level slug is not configured, pass it per report:

status = create_status_client(
    key_id=os.environ["THESEEKER_INGEST_KEY_ID"],
    secret=os.environ["THESEEKER_INGEST_SECRET"],
    endpoint="https://ingest.theseeker.io/v1/events",
)

status.report("degraded", latency_ms=950, slug="checkout-api")

Event shape

The SDK sends a single top-level event:

{"slug":"homepage","result":"ok","latencyMs":123,"message":"homepage responded normally","metrics":{"dnsMs":12}}

Valid results are ok, degraded, and down.

Signing

Requests include X-Ingest-Key-Id, X-Timestamp, X-Nonce, and X-Signature. The signed payload is:

METHOD.upper() + PATH + TIMESTAMP + NONCE + sha256_hex(body_bytes)

The same compact JSON bytes are used for signing and transmission. Both report and feedback requests are single-attempt calls; transport and HTTP errors are raised without SDK retries.

Error tracking

Use a project ingest key with errors:write and select exactly one property by domain or property_id. Error reporting is synchronous, single-attempt, and returns {"ok": bool, "status": int | None, "issue_id": str | None}. By default transport or API errors return ok: False; set raise_errors=True to propagate them. An empty capture_exception() outside an exception handler returns ok: False without sending a request.

import os
from theseeker_status import create_error_client

errors = create_error_client(
    os.environ["THESEEKER_INGEST_KEY_ID"],
    os.environ["THESEEKER_INGEST_SECRET"],
    domain="example.com",
    release="1.2.3",
    environment="production",
)
errors.set_user("user-123")
errors.set_tag("service", "checkout")
errors.add_breadcrumb(category="log", message="checkout started")
try:
    raise RuntimeError("checkout failed")
except RuntimeError:
    print(errors.capture_exception())

errors.install_excepthook()  # chains existing sys and threading exception hooks

For Django, capture view exceptions in process_exception while allowing Django's exception handling to continue:

class ErrorMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        return self.get_response(request)

    def process_exception(self, request, exception):
        errors.capture_exception(exception)
        return None

For FastAPI, an HTTP middleware can use the same pattern:

@app.middleware("http")
async def capture_errors(request, call_next):
    try:
        return await call_next(request)
    except Exception as exc:
        errors.capture_exception(exc)
        raise

capture_message("message") sends a non-exception event. Requests POST compact JSON to /api/error/server, with platform: "python", exception type, message, stack, innermost-first frames and up to 50 breadcrumbs. Frames carry source context when available. Breadcrumb messages and string data redact email-like text, bearer credentials, and digit runs of at least 12. Never add form field values to breadcrumbs. Requests are HMAC-SHA256 signed using the exact bytes sent on the wire; capture_exception() inside an except block also accepts an omitted exception argument.