# Healthcheck middleware plugins

class oslo_middleware.healthcheck.Healthcheck(application: WSGIApplication | None, conf: dict[str, ty.Any] | cfg.ConfigOpts | None = None)

  Healthcheck application used for monitoring.

  It will respond 200 with “OK” as the body. Or a 503 with the reason as the body if one of the backends reports an application issue.

  This is useful for the following reasons:

  - Load balancers can ‘ping’ this url to determine service availability.

  - Provides an endpoint that is similar to ‘mod_status’ in apache which can provide details (or no details, depending on if configured) about the activity of the server.

  - (and more)

  Note

  This middleware indicates that the API is accessible but it does indicate that it is necessarily functional or that any other API request will actually work.

  Example requests/responses (not detailed mode):

      $ curl -i -X HEAD "http://0.0.0.0:8775/healthcheck"
      HTTP/1.1 204 No Content
      Content-Type: text/plain; charset=UTF-8
      Content-Length: 0
      Date: Fri, 11 Sep 2015 18:55:08 GMT

      $ curl -i -X GET "http://0.0.0.0:8775/healthcheck"
      HTTP/1.1 200 OK
      Content-Type: text/plain; charset=UTF-8
      Content-Length: 2
      Date: Fri, 11 Sep 2015 18:55:43 GMT

      OK

      $ curl -X GET -i -H "Accept: application/json" "http://0.0.0.0:8775/healthcheck"
      HTTP/1.0 200 OK
      Date: Wed, 24 Aug 2016 06:09:58 GMT
      Content-Type: application/json
      Content-Length: 63

      {
          "detailed": false,
          "reasons": [
              "OK"
          ]
      }

      $ curl -X GET -i -H "Accept: text/html" "http://0.0.0.0:8775/healthcheck"
      HTTP/1.0 200 OK
      Date: Wed, 24 Aug 2016 06:10:42 GMT
      Content-Type: text/html; charset=UTF-8
      Content-Length: 239

      <HTML>
      <HEAD><TITLE>Healthcheck Status</TITLE></HEAD>
      <BODY>

      <H2>Result of 1 checks:</H2>
      <TABLE bgcolor="#ffffff" border="1">
      <TBODY>
      <TR>

      <TH>
      Reason
      </TH>
      </TR>
      <TR>
          <TD>OK</TD>
      </TR>
      </TBODY>
      </TABLE>
      <HR></HR>

      </BODY>

  Example requests/responses (detailed mode):

      $ curl -X GET -i -H "Accept: application/json" "http://0.0.0.0:8775/healthcheck"
      HTTP/1.0 200 OK
      Date: Wed, 24 Aug 2016 06:11:59 GMT
      Content-Type: application/json
      Content-Length: 3480

      {
          "detailed": true,
          "gc": {
              "counts": [
                  293,
                  10,
                  5
              ],
              "threshold": [
                  700,
                  10,
                  10
              ]
          },
          "greenthreads": [
             ...
          ],
          "now": "2016-08-24 06:11:59.419267",
          "platform": "Linux-4.2.0-27-generic-x86_64-with-Ubuntu-14.04-trusty",
          "python_version": "2.7.6 (default, Jun 22 2015, 17:58:13) \n[GCC 4.8.2]",
          "reasons": [
              {
                  "class": "HealthcheckResult",
                  "details": "Path '/tmp/dead' was not found",
                  "reason": "OK"
              }
          ],
          "threads": [
              ...
          ]
      }

      $ curl -X GET -i -H "Accept: text/html" "http://0.0.0.0:8775/healthcheck"
      HTTP/1.0 200 OK
      Date: Wed, 24 Aug 2016 06:36:07 GMT
      Content-Type: text/html; charset=UTF-8
      Content-Length: 6838

      <HTML>
      <HEAD><TITLE>Healthcheck Status</TITLE></HEAD>
      <BODY>
      <H1>Server status</H1>
      <B>Server hostname:</B><PRE>...</PRE>
      <B>Current time:</B><PRE>2016-08-24 06:36:07.302559</PRE>
      <B>Python version:</B><PRE>2.7.6 (default, Jun 22 2015, 17:58:13)
      [GCC 4.8.2]</PRE>
      <B>Platform:</B><PRE>Linux-4.2.0-27-generic-x86_64-with-Ubuntu-14.04-trusty</PRE>
      <HR></HR>
      <H2>Garbage collector:</H2>
      <B>Counts:</B><PRE>(77, 1, 6)</PRE>
      <B>Thresholds:</B><PRE>(700, 10, 10)</PRE>

      <HR></HR>
      <H2>Result of 1 checks:</H2>
      <TABLE bgcolor="#ffffff" border="1">
      <TBODY>
      <TR>
      <TH>
      Kind
      </TH>
      <TH>
      Reason
      </TH>
      <TH>
      Details
      </TH>

      </TR>
      <TR>
      <TD>HealthcheckResult</TD>
          <TD>OK</TD>
      <TD>Path &#39;/tmp/dead&#39; was not found</TD>
      </TR>
      </TBODY>
      </TABLE>
      <HR></HR>
      <H2>1 greenthread(s) active:</H2>
      <TABLE bgcolor="#ffffff" border="1">
      <TBODY>
      <TR>
          <TD><PRE>  File &#34;oslo_middleware/healthcheck/__main__.py&#34;, line 94, in &lt;module&gt;
          main()
        File &#34;oslo_middleware/healthcheck/__main__.py&#34;, line 90, in main
          server.serve_forever()
        ...
      </PRE></TD>
      </TR>
      </TBODY>
      </TABLE>
      <HR></HR>
      <H2>1 thread(s) active:</H2>
      <TABLE bgcolor="#ffffff" border="1">
      <TBODY>
      <TR>
          <TD><PRE>  File &#34;oslo_middleware/healthcheck/__main__.py&#34;, line 94, in &lt;module&gt;
          main()
        File &#34;oslo_middleware/healthcheck/__main__.py&#34;, line 90, in main
          server.serve_forever()
        ....
      </TR>
      </TBODY>
      </TABLE>
      </BODY>
      </HTML>

  Example of paste configuration:

      [app:healthcheck]
      use = egg:oslo.middleware:healthcheck
      backends = disable_by_file
      disable_by_file_path = /var/run/nova/healthcheck_disable

      [pipeline:public_api]
      pipeline = healthcheck sizelimit [...] public_service

  Multiple app sections can be defined if it desired to have pipelines with different healthcheck configuration, example:

      [composite:public_api]
      use = egg:Paste#urlmap
      / = public_api_pipeline
      /healthcheck = healthcheck_public

      [composite:admin_api]
      use = egg:Paste#urlmap
      / = admin_api_pipeline
      /healthcheck = healthcheck_admin

      [pipeline:public_api_pipeline]
      pipeline = sizelimit [...] public_service

      [pipeline:admin_api_pipeline]
      pipeline = sizelimit [...] admin_service

      [app:healthcheck_public]
      use = egg:oslo.middleware:healthcheck
      backends = disable_by_file
      disable_by_file_path = /var/run/nova/healthcheck_public_disable

      [app:healthcheck_admin]
      use = egg:oslo.middleware:healthcheck
      backends = disable_by_file
      disable_by_file_path = /var/run/nova/healthcheck_admin_disable

  classmethod app_factory(global_conf: dict[str, Any] | None, **local_conf: Any) → Self

    Factory method for paste.deploy.

    Parameters:

      - global_conf – dict of options for all middlewares (usually the [DEFAULT] section of the paste deploy configuration file)

      - local_conf – options dedicated to this middleware (usually the option defined in the middleware section of the paste deploy configuration file)

  classmethod factory(global_conf: dict[str, ty.Any] | None, **local_conf: ty.Any) → ty.Callable[[WSGIApplication], base.MiddlewareType]

    Factory method for paste.deploy.

    Parameters:

      - global_conf – dict of options for all middlewares (usually the `[DEFAULT]` section of the paste deploy configuration file)

      - local_conf – options dedicated to this middleware (usually the option defined in the middleware’s section of the paste deploy configuration file)

class oslo_middleware.healthcheck.Reason

class oslo_middleware.healthcheck.disable_by_file.DisableByFileHealthcheck(oslo_conf: cfg.ConfigOpts, conf: dict[str, ty.Any])

  DisableByFile healthcheck middleware plugin

  This plugin checks presence of a file to report if the service is unavailable or not.

  Example of middleware configuration:

      [filter:healthcheck]
      paste.filter_factory = oslo_middleware:Healthcheck.factory
      path = /healthcheck
      backends = disable_by_file
      disable_by_file_path = /var/run/nova/healthcheck_disable
      # set to True to enable detailed output, False is the default
      detailed = False

  healthcheck(server_port: int) → HealthcheckResult

    method called by the healthcheck middleware

    return: HealthcheckResult object

class oslo_middleware.healthcheck.disable_by_file.DisableByFilesPortsHealthcheck(oslo_conf: cfg.ConfigOpts, conf: dict[str, ty.Any])

  DisableByFilesPorts healthcheck middleware plugin

  This plugin checks presence of a file that is provided for a application running on a certain port to report if the service is unavailable or not.

  Example of middleware configuration:

      [filter:healthcheck]
      paste.filter_factory = oslo_middleware:Healthcheck.factory
      path = /healthcheck
      backends = disable_by_files_ports
      disable_by_file_paths = 5000:/var/run/keystone/healthcheck_disable,             35357:/var/run/keystone/admin_healthcheck_disable
      # set to True to enable detailed output, False is the default
      detailed = False

  healthcheck(server_port: int) → HealthcheckResult

    method called by the healthcheck middleware

    return: HealthcheckResult object

class oslo_middleware.healthcheck.enable_by_files.EnableByFilesHealthcheck(oslo_conf: cfg.ConfigOpts, conf: dict[str, Any])

  EnableByFilesHealthcheck healthcheck middleware plugin

  This plugin checks presence of a file at a specified location.

  Example of middleware configuration:

      [app:healthcheck]
      paste.app_factory = oslo_middleware:Healthcheck.app_factory
      path = /healthcheck
      backends = enable_by_files
      enable_by_file_paths = /var/lib/glance/images/.marker,
          /var/lib/glance/os_glance_staging_store/.marker
      # set to True to enable detailed output, False is the default
      detailed = False

  healthcheck(server_port: int) → HealthcheckResult

    method called by the healthcheck middleware

    return: HealthcheckResult object

## Available Plugins

### disable_by_file

DisableByFile healthcheck middleware plugin

This plugin checks presence of a file to report if the service is unavailable or not.

Example of middleware configuration:

    [filter:healthcheck]
    paste.filter_factory = oslo_middleware:Healthcheck.factory
    path = /healthcheck
    backends = disable_by_file
    disable_by_file_path = /var/run/nova/healthcheck_disable
    # set to True to enable detailed output, False is the default
    detailed = False

### disable_by_files_ports

DisableByFilesPorts healthcheck middleware plugin

This plugin checks presence of a file that is provided for a application running on a certain port to report if the service is unavailable or not.

Example of middleware configuration:

    [filter:healthcheck]
    paste.filter_factory = oslo_middleware:Healthcheck.factory
    path = /healthcheck
    backends = disable_by_files_ports
    disable_by_file_paths = 5000:/var/run/keystone/healthcheck_disable,             35357:/var/run/keystone/admin_healthcheck_disable
    # set to True to enable detailed output, False is the default
    detailed = False

### enable_by_files

EnableByFilesHealthcheck healthcheck middleware plugin

This plugin checks presence of a file at a specified location.

Example of middleware configuration:

    [app:healthcheck]
    paste.app_factory = oslo_middleware:Healthcheck.app_factory
    path = /healthcheck
    backends = enable_by_files
    enable_by_file_paths = /var/lib/glance/images/.marker,
        /var/lib/glance/os_glance_staging_store/.marker
    # set to True to enable detailed output, False is the default
    detailed = False

this page last updated: 2026-03-26 20:17:45

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug