Bloomreach

Bloomreach Documentation version

This article covers a Bloomreach Experience Manager version 12. There's an updated version available that covers our most recent release.

Run / Deploy Application / PingFilter

PingFilter

This feature is available since version 12.2.0

Why Use the PingFilter?

Both the PingServlet and PingFilter typically are used by load balancers to find out whether a cluster node is available. When they return a status 200 (HttpServletResponse.SC_OK), it means the cluster node is ready to serve requests and the load balancer most likely will send some traffic to the cluster node. There is only a big difference in how a ping request is handled by the PingServlet and the PingFilter, see below.  It is always better to use the PingFilter instead of the PingServlet, but if you have an extremely large HST configuration, it is much better to use the PingFilter because as opposed to the PingServlet, the PingFilter always returns instantly with a response. 

It is always better to use the PingFilter, and in case you have an extremely large HST configuration, it is strongly recommended to use the PingFilter instead of PingServlet. 

By default, we still bootstrap a project with the PingServlet. This is to ensure backwards-compatibilty.

Difference PingFilter/PingServlet

The PingServlet in the site webapp only returns after the repository has been completely initialised and up & running and the entire HST in memory model has been loaded and build. In case you have a gigantic HST configuration (for example containing 100.000 configuration JCR nodes), the initial load of the model can take a considerable time since every JCR Node needs to be fetched from the database right after startup (since not yet present in the bundle cache). Assuming 1 ms per database fetch results in the first ping request to take at least 100 seconds (for just fetching the configuration nodes). During this 100 seconds, the loadbalancer can already decide the cluster node is not available and drop it again. 

Opposed to the  PingServlet, the PingFilter returns instantly, either with a status 200 (HttpServletResponse.SC_OK) meaning the loadbalancer can start sending traffic to the cluster node, or with a 503 (HttpServletResponse.SC_SERVICE_UNAVAILABLE) meaning the cluster node is not yet ready to serve requests. After more pings to the  PingFilter, after some time, the 503 changes into status 200 meaning the application is ready to serve requests.

Prerequisite 

If you want to use the default PingFilter setup, it is not allowed to have in the site web.xml the following context-param configuration:

<context-param>
  <param-name>hst-lazy-configuration-loading</param-name>
  <param-value>true</param-value>
</context-param>

By default, the above context-param is not present in your web.xml so if present, it has been added in the end project implementation. If hst-lazy-configuration-loading = true is configured, the PingFilter can still be used by specifying the PingFilter init-param:

<init-param>
  <param-name>hst-availability-check</param-name>
  <param-value>hstServices</param-value>
</init-param>

or:

<init-param>
  <param-name>hst-availability-check</param-name>
  <param-value>repositoryAvailability</param-value>
</init-param>

See below for more details on the repositoryAvailability or hstServices params.

Configure the PingFilter in the Site Webapp

In the HST site webapp's web.xml, add PingFilter before HstFilter:

<filter>
  <filter-name>PingFilter</filter-name>
  <filter-class>org.hippoecm.hst.container.PingFilter</filter-class>
</filter>

and filter-mapping (before the HstFilter mapping):

<filter-mapping>
  <filter-name>PingFilter</filter-name>
  <url-pattern>/ping/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
</filter-mapping>

If present, remove the PingServlet:

<servlet>
  <servlet-name>PingServlet</servlet-name>
  <servlet-class>org.hippoecm.hst.servlet.HstPingServlet</servlet-class>
</servlet>

and its mapping:

<servlet-mapping>
  <servlet-name>PingServlet</servlet-name>
  <url-pattern>/ping/*</url-pattern>
</servlet-mapping>

Now, ping requests, for example http://www.example.org/ping, are handled by the PingFilter instead of the PingServlet.

PingFilter Configuration Options

Only use the configuration options described below if you have really explicit reasons for it. Otherwise always stick to the default which tests the availability of the presence of the HST configuration nodes in memory

By default, the PingFilter checks for the availability of the HST configuration nodes. If not yet available, a status 503 is returned instantly. If not the presence of the HST configuration nodes in memory is required, but the presence of a running repository, you can configure:

<filter>
  <filter-name>PingFilter</filter-name>
  <filter-class>org.hippoecm.hst.container.PingFilter</filter-class>
  <init-param>
    <param-name>hst-availability-check</param-name>
    <param-value>repositoryAvailability</param-value>
  </init-param>
</filter>

If instead of the repository, the HST Services (and HST Spring Component Manager) only need to be available, you can configure:

<filter>
  <filter-name>PingFilter</filter-name>
  <filter-class>org.hippoecm.hst.container.PingFilter</filter-class>
  <init-param>
    <param-name>hst-availability-check</param-name>
    <param-value>hstServices</param-value>
  </init-param>
</filter>

Custom error message

Since versions 12.5.1 and 12.6.1 the PingFilter supports a "custom-error-message" init parameter in web.xml or better, as context parameter in the context.xml. If configured, the PingFilter returns a response with status 503 (unavailable) with the custom error message printed to the response.

<Context>
    <!-- Make org.hippoecm.hst.container.PingFilter return a 503 status -->
    <Parameter name="custom-error-message" value="This site is down on behalf an upgrade"/>
</Context>

 

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?