WSGI Middleware
Python

WSGI (Web Server Gateway Interface) is a specification that defines the protocol between web servers and Python web applications.

The Blackfire Python SDK contains a middleware easing the integration with WSGI web applications.

The integrations we provide for Django, Flask, Odoo are extending the BlackfireWSGIMiddleware. They could serve as examples helping the creation of a new middleware.

Integrations with other frameworks could benefit the Blackfire community. Please consider contributing your code.

The Blackfire Python SDK is available with the Blackfire Python Package.

Create a class extending the BlackfireWSGIMiddleware.

The FRAMEWORK variable must be set; it should describe the instrumented application.

1
2
3
4
5
6
7
from blackfire.hooks.wsgi import BlackfireWSGIMiddleware

class BlackfireFooBarMiddleware(BlackfireWSGIMiddleware):

    FRAMEWORK = 'Foo-Bar'

    ...

A get_view_name method must be defined to have the requests of your WSGI-based application be instrumented by Blackfire Monitoring.

This function is required only for the monitoring of your application. Its definition can be omitted if you are not considering it.

The get_view_name method retrieves the view name executing or handling the HTTP request. Blackfire Monitoring relies on this information to group requests in the monitoring dashboard.

If it returns None, the viewname will be grouped with other Unnamed Transactions

The function receives 1 parameter:

  • environ is a dictionary that contains the HTTP request headers and other metadata.

The function should return a string or None.

1
2
3
4
5
6
7
8
from blackfire.hooks.wsgi import BlackfireWSGIMiddleware

class BlackfireFooBarMiddleware(BlackfireWSGIMiddleware):

    FRAMEWORK = 'Foo-Bar'

    def get_view_name(self, environ):
        # implementation ...

A build_blackfire_yml_response method must be defined to be able to use Blackfire Builds.

This function is required only by Blackfire Build. Its definition can be omitted if you are not considering the Synthetic Monitoring of your application.

This function is called to handle Blackfire builds. When a build POST request is received, this function gets called to build a framework specific response that contains the .blackfire.yaml file contents.

The function receives 4 parameters:

  • blackfireyml_content: the content of the .blackfire.yaml file;
  • agent_response: a tuple of values received from the Agent connection when the build request is authenticated. None otherwise. If set, the tuple should be sent back as headers in the HTTP response;
  • environ is a dictionary that contains the HTTP request headers and other metadata;
  • start_response is a callable used to begin the HTTP response.

The build_blackfire_yml_response function should return a framework specific HTTP response.

In the example below, the function returns an instance of werkzeug.wrappers.Response.

In the Django middleware, it returns an instance of django.http.HttpResponse.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from blackfire.hooks.wsgi import BlackfireWSGIMiddleware

class OdooMiddleware(BlackfireWSGIMiddleware):

    FRAMEWORK = 'odoo'

    def build_blackfire_yml_response(
        self, blackfireyml_content, agent_response, environ, start_response
    ):
        from werkzeug.wrappers import Response

        # The .blackfire.yaml file should only be sent for authentified request
        if agent_response:
            return Response(
                response=blackfireyml_content or '', headers=[agent_response]
            )(environ, start_response)

        return Response()(environ, start_response)