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.

Filtering, hooks and delivery

import re
import errorgap

def before_notify(notice):
    if notice["errors"][0]["type"] == "Http404":
        return False                      # drop it
    notice["context"]["team"] = "billing"  # or change it

errorgap.init(
    filter_keys=("password", "token", re.compile(r"^ssn$")),
    ignore_environments=["test"],
    before_notify=before_notify,
)

filter_keys (substrings or compiled patterns) are masked at any depth in params and session. Values that cannot be serialized, reference cycles and oversized strings or collections are cut rather than losing the notice. An exception's cause chain (raise … from, or the exception being handled when it was raised) is reported with it, and the Django middleware names the signed-in user.

Notices are queued (at most queue_size, oldest dropped first) and sent by a background thread with a timeout per request. A send that fails on the network or with a 5xx is retried up to three times; after a 429 the SDK stops sending for the server's Retry-After. With release unset it is read from ERRORGAP_RELEASE, the hosting platform's commit variable or the git checkout.

Remote settings

Errors and performance data can each be switched off for a project in errorgap (Project settings › What SDKs send). Running apps follow within ten minutes, with no deploy: the SDK re-reads GET /api/projects/:slug/config on a background thread. If errorgap cannot be reached, everything stays on. errorgap.init(remote_settings=False) (or ERRORGAP_REMOTE_SETTINGS=false) ignores the project's switches.

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).

Other frameworks, Celery and logging

Import the submodule you use (from errorgap.celery import install). Celery tasks are timed as job transactions and a failed task is reported with its name, id, queue, retry count and arguments. The logging handler reports logger.exception(...) as that exception and a plain logger.error("…") as a LoggedError; it reports ERROR and above unless you pass a level.

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.