Module resty.healthcheck

Healthcheck library for OpenResty.

Some notes on the usage of this library:

  • Each target will have 4 counters, 1 success counter and 3 failure counters ('http', 'tcp', and 'timeout'). Any failure will only reset the success counter, but a success will reset all three failure counters.

  • All targets are uniquely identified by their IP address and port number combination, most functions take those as arguments.

  • All keys in the SHM will be namespaced by the healthchecker name as provided to the new function. Hence no collissions will occur on shm-keys as long as the name is unique.

  • Active healthchecks will be synchronized across workers, such that only a single active healthcheck runs.

  • Events will be raised in every worker, see lua-resty-worker-events for details.

Info:

  • Copyright: 2017 Kong Inc.
  • License: Apache 2.0
  • Author: Hisham Muhammad, Thijs Schreijer

Tables

checker.events The list of potential events generated.

Node management

checker:add_target (ip, port, hostname, healthy) Add a target to the healthchecker.
checker:clear () Clear all healthcheck data.
checker:get_target_status (ip, port) Get the current status of the target.
checker:remove_target (ip, port) Remove a target from the healthchecker.

Health management

checker:report_failure (ip, port, check) Report a health failure.
checker:report_http_status (ip, port, http_status, check) Report a http response code.
checker:report_success (ip, port, check) Report a health success.
checker:report_tcp_failure (ip, port, operation, check) Report a failure on TCP level.
checker:report_timeout (ip, port, check) Report a timeout failure.
checker:set_target_status (ip, port, mode) Sets the current status of the target.

Initializing

checker:start () Start the background health checks.
checker:stop () Stop the background health checks.
new (opts) Creates a new health-checker instance.


Tables

checker.events
The list of potential events generated. The checker.EVENT_SOURCE field can be used to subscribe to the events, see the example below. Each of the events will get a table passed containing the target details ip, port, and hostname. See lua-resty-worker-events.

Fields:

  • remove Event raised when a target is removed from the checker.
  • healthy This event is raised when the target status changed to healthy (and when a target is added as healthy).
  • unhealthy This event is raised when the target status changed to unhealthy (and when a target is added as unhealthy).

Usage:

    -- Register for all events from my_checker
    local event_callback = function(target, event, source, source_PID)
      local t = target.ip .. ":" .. target.port .." by name '" ..
                target.hostname .. "' ")
    
      if event == my_checker.events.remove then
        print(t .. "has been removed")
    
      elseif event == my_checker.events.healthy then
        print(t .. "is now healthy")
    
      elseif event == my_checker.events.unhealthy then
        print(t .. "is now unhealthy")
    
      else
        print("received an unknown event: " .. event)
      end
    end
    
    worker_events.register(event_callback, my_checker.EVENT_SOURCE)

Node management

checker:add_target (ip, port, hostname, healthy)
Add a target to the healthchecker. When the ip + port combination already exists, it will simply return success (without updating either hostname nor healthy status).

Parameters:

  • ip IP address of the target to check.
  • port the port to check against.
  • hostname (optional) hostname to set as the host header in the the HTTP probe request (defaults to the provided IP address).
  • healthy (optional) a boolean value indicating the initial state, default is true.

Returns:

    true on success, or nil + error on failure.
checker:clear ()
Clear all healthcheck data.

Returns:

    true on success, or nil + error on failure.
checker:get_target_status (ip, port)
Get the current status of the target.

Parameters:

  • ip IP address of the target being checked.
  • port the port being checked against.

Returns:

    true if healthy, false if unhealthy, or nil + error on failure.
checker:remove_target (ip, port)
Remove a target from the healthchecker. The target not existing is not considered an error.

Parameters:

  • ip IP address of the target being checked.
  • port the port being checked against.

Returns:

    true on success, or nil + error on failure.

Health management

Functions that allow reporting of failures/successes for passive checks.
checker:report_failure (ip, port, check)
Report a health failure. Reports a health failure which will count against the number of occurrences required to make a target "fall". The type of healthchecker, "tcp" or "http" (see new) determines against which counter the occurence goes.

Parameters:

  • ip IP address of the target being checked.
  • port the port being checked against.
  • check (optional) the type of check, either "passive" or "active", default "passive".

Returns:

    true on success, or nil + error on failure.
checker:report_http_status (ip, port, http_status, check)
Report a http response code. How the code is interpreted is based on the configuration for healthy and unhealthy statuses. If it is in neither strategy, it will be ignored.

Parameters:

  • ip IP address of the target being checked.
  • port the port being checked against.
  • http_status the http statuscode, or nil to report an invalid http response.
  • check (optional) the type of check, either "passive" or "active", default "passive".

Returns:

    true on success, nil if the status was ignored (not in active or passive health check lists) or nil + error on failure.
checker:report_success (ip, port, check)
Report a health success. Reports a health success which will count against the number of occurrences required to make a target "rise".

Parameters:

  • ip IP address of the target being checked.
  • port the port being checked against.
  • check (optional) the type of check, either "passive" or "active", default "passive".

Returns:

    true on success, or nil + error on failure.
checker:report_tcp_failure (ip, port, operation, check)
Report a failure on TCP level.

Parameters:

  • ip IP address of the target being checked.
  • port the port being checked against.
  • operation The socket operation that failed: "connect", "send" or "receive". TODO check what kind of information we get from the OpenResty layer in order to tell these error conditions apart https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/balancer.md#getlastfailure
  • check (optional) the type of check, either "passive" or "active", default "passive".

Returns:

    true on success, or nil + error on failure.
checker:report_timeout (ip, port, check)
Report a timeout failure.

Parameters:

  • ip IP address of the target being checked.
  • port the port being checked against.
  • check (optional) the type of check, either "passive" or "active", default "passive".

Returns:

    true on success, or nil + error on failure.
checker:set_target_status (ip, port, mode)
Sets the current status of the target. This will immediately set the status and clear its counters.

Parameters:

  • ip IP address of the target being checked
  • port the port being checked against
  • mode boolean: true for healthy, false for unhealthy

Returns:

    true on success, or nil + error on failure

Initializing

checker:start ()
Start the background health checks.

Returns:

    true, or nil + error.
checker:stop ()
Stop the background health checks. The timers will be flagged to exit, but will not exit immediately. Only after the current timers have expired they will be marked as stopped.

Returns:

    true
new (opts)
Creates a new health-checker instance. It will be started upon creation.

NOTE: the returned checker object must be anchored, if not it will be removed by Lua's garbage collector and the healthchecks will cease to run.

Parameters:

  • opts

    table with checker options. Options are:

    • name: name of the health checker
    • shm_name: the name of the lua_shared_dict specified in the Nginx configuration to use
    • type: "http", "https" or "tcp"
    • checks.active.timeout: socket timeout for active checks (in seconds)
    • checks.active.concurrency: number of targets to check concurrently
    • checks.active.http_path: path to use in GET HTTP request to run on active checks
    • checks.active.healthy.interval: interval between checks for healthy targets (in seconds)
    • checks.active.healthy.http_statuses: which HTTP statuses to consider a success
    • checks.active.healthy.successes: number of successes to consider a target healthy
    • checks.active.unhealthy.interval: interval between checks for unhealthy targets (in seconds)
    • checks.active.unhealthy.http_statuses: which HTTP statuses to consider a failure
    • checks.active.unhealthy.tcp_failures: number of TCP failures to consider a target unhealthy
    • checks.active.unhealthy.timeouts: number of timeouts to consider a target unhealthy
    • checks.active.unhealthy.http_failures: number of HTTP failures to consider a target unhealthy
    • checks.passive.healthy.http_statuses: which HTTP statuses to consider a failure
    • checks.passive.healthy.successes: number of successes to consider a target healthy
    • checks.passive.unhealthy.http_statuses: which HTTP statuses to consider a success
    • checks.passive.unhealthy.tcp_failures: number of TCP failures to consider a target unhealthy
    • checks.passive.unhealthy.timeouts: number of timeouts to consider a target unhealthy
    • checks.passive.unhealthy.http_failures: number of HTTP failures to consider a target unhealthy

Returns:

    checker object, or nil + error
generated by LDoc 1.4.6 Last updated 2017-11-29 20:00:07