Skip to main content

Introduction

After you complete the Python installation, unhandled exceptions are reported automatically. Call lerix.capture_exception() to report handled exceptions yourself with extra context.

Automatic capture

lerix.init() installs two process-level hooks:
  • sys.excepthook. An exception that escapes the main thread is reported, given up to flush_timeout seconds to leave, and then handed to the previous hook so the traceback is still printed and the interpreter exits as it normally would. KeyboardInterrupt and SystemExit are not reported.
  • threading.excepthook. An exception that kills a threading.Thread is reported with the thread name in metadata.thread.
Set capture_unhandled=False to skip both.

asyncio

Exceptions inside tasks whose result is never awaited are only logged by asyncio. Call install_asyncio_handler after creating the loop to report them too:

Web frameworks

Frameworks turn exceptions into a 500 response before they reach the process hooks, so each one has its own hook. They all attach the request method, URL, route, status code and the X-Request-Id header when present, under metadata.request, and then let the framework’s own error handling run unchanged.

Change what is reported

Every hook accepts a should_capture callable that receives the exception and the HTTP status that will be sent (when known) and returns whether to report it:
main.py
For Flask pass it to LerixFlask(app, should_capture=...). For Django set it on the class in settings.py:
settings.py

Several clients

The hooks use the client created by lerix.init(). Pass client= to a hook (or set LerixMiddleware.client for Django) when one process reports to more than one project.

Filtering errors

Requires lerix 0.4.0 or later. Two options decide what leaves the process. They apply to every report, whatever its origin: the framework integrations, sys.excepthook / threading.excepthook / the asyncio handler, and capture_exception / capture_message. Use them for message-based filtering; use should_capture (above) to decide by exception or HTTP status.
main.py
  • ignore_errors (list[str | re.Pattern]) runs first, then before_send sees only what’s left.
  • The message matched and passed to before_send is the issue title shown in the dashboard, for example ValueError: boom.
  • lerix.ErrorEvent is a dataclass with message, stack (list of frame strings), type (BugType), severity (BugSeverity) and metadata (what you passed to the capture call, or the request context from an integration). Device, app and runtime details are added after the hook, which runs on the thread that captured the error.
  • If before_send raises, the original event is sent and the error is only logged. It is never reported or re-raised.
  • A dropped report does not pin its request’s trace.
Lerix also groups repeated errors into one issue and filters common noise on the server, for every SDK version. See How errors are grouped into issues.

Report an error manually

orders.py
Inside an except block you can leave the exception out and capture_exception() picks up the one being handled. It never raises and never blocks: the report is sent from a background thread, and the returned Future resolves once the report has been accepted or given up on. Use capture_message for something that was not raised:

Parameters

BugType values

BugSeverity values

What is attached to a report

Flush before exit

Reports are sent in the background. Long-running servers do not need to do anything, and the SDK flushes on normal interpreter exit. In short-lived scripts, workers or serverless handlers, call flush() before returning:

Other functions

LerixClient can also be instantiated directly, with the same options as init(), when you need more than one client in a process.

Disable in tests

Pass enabled=False to turn every call into a no-op without changing your code: