backlash 0.5.0

About backlash

backlash is a swiss army knife for web applications debugging, which provides:

• An Interactive In Browser Debugger for WSGI and ASGI applications, based on a Werkzeug Debugger fork

• Crash reporting by email and on Sentry (WSGI)

• Slow requests reporting by email and on Sentry (WSGI).

Backlash was born as a replacement for WebError in TurboGears2.3 versions.

Installing

backlash can be installed from pypi:

pip install backlash

should just work for most of the users. backlash has no runtime dependencies.

Debugging and Console

Backlash supports both debugging applications on crash and realtime console, both based on the Werkzeug Debugger.

The debugging function is provided by the WsgiDebuggedApplication middleware for WSGI applications and the AsgiDebuggedApplication middleware for ASGI applications (Starlette, FastAPI, bare ASGI apps). Wrapping your application with the middleware will intercept any exception and display the traceback and an interactive console in your browser.

An interactive console will also be always available at /__console__ path.

backlash.DebuggedApplication (importable also as backlash.debug.DebuggedApplication) is the same class as backlash.wsgi.WsgiDebuggedApplication, so existing WSGI setups keep working unchanged.

from backlash.asgi import AsgiDebuggedApplication

app = AsgiDebuggedApplication(app)

app.add_middleware(AsgiDebuggedApplication)

def _turbogears_backlash_context(environ):
    tgl = environ.get('tg.locals')
    return {'request':getattr(tgl, 'request', None)}

app = backlash.DebuggedApplication(app, context_injectors=[_turbogears_backlash_context])

Exception Tracing

The TraceErrorsMiddleware provides a WSGI middleware that intercepts any exception raised during execution, retrieves a traceback object and provides it to one or more reporters to log the error.

By default the EmailReporter and SentryReporter are provided to send error reports by email and on Sentry.

The EmailReporter supports most of the options WebError ErrorMiddleware to provide some kind of backward compatibility and make possible a quick transition.

While this function is easily replicable using the python logging SMTPHandler, the TraceErrorsMiddleware is explicitly meant for web applications crash reporting which has the benefit of being able to provide more complete information and keep a clear and separate process in managing errors.

from backlash.trace_errors import EmailReporter

def _turbogears_backlash_context(environ):
   tgl = environ.get('tg.locals')
   return {'request':getattr(tgl, 'request', None)}

app = backlash.TraceErrorsMiddleware(app, [EmailReporter(**errorware)],
                                     context_injectors=[_turbogears_backlash_context])

Slow Requests Tracing

The TraceSlowRequestsMiddleware provides a WSGI middleware that tracks requests execution time and reports requests that took more than a specified interval to complete (by default 25 seconds).

It is also possible to exclude a list of paths that start with a specified string to avoid reporting long polling connections or other kind of requests that are expected to have a long life spawn.

from backlash.trace_errors import EmailReporter

def _turbogears_backlash_context(environ):
   tgl = environ.get('tg.locals')
   return {'request':getattr(tgl, 'request', None)}

app = backlash.TraceSlowRequestsMiddleware(app, [EmailReporter(**errorware)],
                                           interval=25, exclude_paths=None,
                                           context_injectors=[_turbogears_backlash_context])