1. Documentation
  2. Getting Up and Running
  3. Bypassing Reverse Proxy, Cache, and Content Delivery Networks (CDN)

Bypassing Reverse Proxy, Cache, and Content Delivery Networks (CDN)

When using a reverse proxy (Varnish, Fastly, HA Proxy, Nginx…), a load balancer or a content delivery network (CDN) sitting in front of your application, you need to bypass them when profiling with Blackfire.

In such context, your infrastructure must:

  • Serve a non-cached response;
  • Not remove the specific HTTP headers injected by the Blackfire browser extension, the Blackfire CLI client, or the Blackfire Player (read further below);
  • Target a specific server running your application, behind the proxy.

HTTP Headers

In order to successfully profile your application, several HTTP headers are processed by the client. These headers are required to pass through to and from your application (and the Blacfkire probe).

Request Headers

Any Blackfire client, whether it is the Blackfire browser extension, the Blackfire CLI client, or the Blackfire Player, injects a specific HTTP header into each Request to profile a resource: X-Blackfire-Query. This header contains mandatory information for the probe, including the signature (read How does Blackfire work for further details).

Response Headers

The following HTTP response headers need to be preserved:

  • X-Blackfire-Response
  • X-Blackfire-Error

Those headers are needed by the Blackfire clients, especially when profiling multiple samples of a single page or script.

Load Balancer

If you are using multiple application servers behind a load-balancer, you have several options to profile your application:

  • The recommended option is to:
  • Install the Blackfire Probe and the Blackfire Agent on a single server;
  • Configure the load balancer to route all requests containing a header whose name matched X-Blackfire-Query to the configured server.
  • Another option is to:

  • Setup a single Blackfire Agent for all the servers and configure it to listen on the network using a TCP socket:

    1
    socket=tcp://0.0.0.0:8307

    Note

    Please note that using the legacy blackfire-agent package on Linux, the socket configuration is defined in /etc/default/blackfire-agent. You can refer to the /etc/default/blackfire-agent section for more information.

  • Setup the Blackfire Probe on all the servers and configure it using the TCP socket defined above in the php.ini configuration:

    1
    blackfire.agent_socket = tcp://10.0.0.1:8307

Reverse Proxies and CDNs

We provide various integration examples with different reverse proxies and CDNs: