errorgap

Python notifier for Errorgap. Captures exceptions, normalizes tracebacks with bounded source excerpts for readable frames, and ships notices to an Errorgap server. Single package covers plain Python, Django, Flask, and FastAPI.

Install

pip install errorgap

For framework integrations:

pip install "errorgap[django]"   # or [flask], [fastapi]

Requires Python 3.9+.

Configure

import errorgap

errorgap.init(
    endpoint=...,
    project_slug=...,
    api_key=...,
    environment="production",
)

init reads the same values from ERRORGAP_ENDPOINT, ERRORGAP_PROJECT_SLUG, ERRORGAP_PROJECT_ID, and ERRORGAP_API_KEY if you don't pass them. By default it installs a sys.excepthook to catch uncaught exceptions in scripts; pass capture_globals=False to skip.

Manual notification

try:
    risky()
except Exception as exc:
    errorgap.notify(exc, context={"component": "billing"})
    raise

notify returns a DeliveryResult (status, body, error, queued). The SDK never raises.

Django

Add to MIDDLEWARE:

MIDDLEWARE = [
    "errorgap.django.ErrorgapMiddleware",
    # ... your existing middleware ...
]

With apm_enabled=True each request is also an APM transaction grouped by its URL pattern (/orders/<int:order_id>); errors raised during it carry its transaction id, and the browser SDK's x-errorgap-trace header is recorded. Record spans from a view with errorgap.django.spans(request).database(sql, ms).

Flask

from flask import Flask
from errorgap.flask import init_app

app = Flask(__name__)
init_app(app)

init_app also times each request as an APM transaction (sent with apm_enabled=True) grouped by its URL rule (/orders/<int:id>), and errors raised during the request carry its transaction id. Record spans from a view with errorgap.flask.spans():

from errorgap.flask import spans

@app.route("/orders/<int:order_id>")
def order(order_id):
    started = time.perf_counter()
    row = db.execute("SELECT * FROM orders WHERE id = %s", (order_id,)).fetchone()
    spans().database("SELECT * FROM orders WHERE id = %s", (time.perf_counter() - started) * 1000)
    return row

WSGI

Any WSGI app gets the same request transactions from errorgap.wsgi.ErrorgapMiddleware. Set environ["errorgap.route"] to the matched route template to group requests (otherwise the raw path is used).

from errorgap.wsgi import ErrorgapMiddleware

application = ErrorgapMiddleware(application)

Transactions and jobs

with errorgap.track_transaction("GET", "/orders/{id}", "/orders/123") as txn:
    txn.spans.database("SELECT * FROM orders WHERE id = 123", 4.2)
    txn.status_code = 200

with errorgap.track_job("ReceiptJob", queue="mailers") as txn:
    send_receipt()

Both time the block and deliver on exit even if it raises. Errors reported inside carry the transaction id (context.transaction_id), so errorgap shows the error a request raised on its trace. The id lives in a ContextVar, so concurrent threads and asyncio tasks never share one; errorgap.current_transaction_id() returns the id in effect.

Browser trace links

When the errorgap browser SDK (@errorgap/browser 0.3+) is on the page, its API calls send an x-errorgap-trace header. The WSGI, Django and FastAPI middleware (and so Flask's init_app) record it, and track_transaction(..., trace_id=header) accepts it, so errorgap's browser Performance view links each call to the server request that answered it. Malformed values are ignored.

FastAPI

from fastapi import FastAPI
from errorgap.fastapi import ErrorgapMiddleware

app = FastAPI()
app.add_middleware(ErrorgapMiddleware)

With apm_enabled=True each request is also an APM transaction grouped by its route path (/orders/{order_id}); errors raised during it carry its transaction id, and the browser SDK's x-errorgap-trace header is recorded. Record spans from an endpoint with errorgap.fastapi.spans(request).database(sql, ms) (take request: Request as a parameter).

Sign-ins

Report sign-ins to your app; errorgap shows them beside SSH logins in Security › Logins and flags a new IP, country or hour for a user. Off until you opt in, since events carry user names and IPs:

errorgap.init(project_slug="ox-coffee", auth_events=True, app_name="oxcoffee-web")

Django needs nothing else: with ErrorgapMiddleware installed, Django's user_logged_in and user_login_failed signals are reported (the user's get_username(); Django masks the password before the signal). Elsewhere, or for other outcomes:

errorgap.sign_in("success" if ok else "failure", user=email, request=request)
errorgap.sign_in("mfa_failure", user=email, request=request)

Outcomes: success, failure, password_reset, mfa_failure, locked. A Django, Flask or Starlette request supplies the IP, user agent and path (without the query string); behind a proxy, pass ip= yourself. Never pass passwords or tokens; errorgap can also store user names hashed (Security › Logins › Web apps › Privacy).

Configuration reference

Graceful shutdown

errorgap.flush(timeout=5)     # wait for queued deliveries
errorgap.shutdown(timeout=5)  # flush + tear down background thread

Verify

curl -sS -X POST "$ERRORGAP_ENDPOINT/api/projects/$ERRORGAP_PROJECT_SLUG/notices" \
  -H "content-type: application/json" \
  -H "x-errorgap-project-key: $ERRORGAP_API_KEY" \
  -d '{"errors":[{"type":"ErrorgapInstallTest","message":"Errorgap install verification"}],"context":{"environment":"development"}}'

Then trigger a real error and confirm it appears in the Errorgap UI.

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT.