Healthcheck middleware plugins

class oslo_middleware.healthcheck.Healthcheck(*args, **kwargs)

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)

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 filter 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

[filter: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, **local_conf)

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, **local_conf)

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)

class oslo_middleware.healthcheck.disable_by_file.DisableByFileHealthcheck(*args, **kwargs)

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)

method called by the healthcheck middleware

return: HealthcheckResult object

class oslo_middleware.healthcheck.disable_by_file.DisableByFilesPortsHealthcheck(*args, **kwargs)

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)

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