The Send Metrics module allows you to stream user-formatted HAProxy data periodically to an external program at preconfigured URLs.

A good use-case is forwarding load balancer metrics to third-party APIs, such as NS1 to use in making decisions for load shedding.

This module accepts standard HAProxy log-format rules and variables.

Tip

HAProxy Enterprise only: This module requires an active HAProxy Enterprise subscription. Please contact us if you would like to learn more or begin a free trial.

Install Send Metrics

  • Install the Send Metrics module as follows, depending on your platform:

    $ sudo apt install hapee-1.8r2-lb-send-metrics

    or

    $ sudo yum install hapee-1.8r2-lb-send-metrics

Configure Send Metrics

  • In the global section of HAProxy's configuration file /etc/hapee-1.8r2/hapee-lb.conf, add the following lines:

    global
        module-load hapee-lb-send-metrics.so
        send-metrics-debug 127
        send-metrics-url POST http://localhost:8000/v1/feed/__SourceUUID__  xdelay 1m 5s 1s 1s  timeout 100ms  retries 3  log
        send-metrics-header 'X-NSONE-Key: __APIKey__' 'X-Send-Metrics: 42'
        send-metrics-content-type application/json
        send-metrics-data '{ "lga01": { "Hostname": "%H", "Date": "%T", "connections": "%ac" } }'

See the section below for explanations for each directive and their parameters.

Global parameters

The Send Metrics module accepts the following directives in the global section:

  • send-metrics-url post <url> [delay <u> | xdelay <u s b r>] [timeout <t>] [retries <n>] [log] [dontlog-normal] [param*] (required): Tells HAProxy to update data metrics over HTTP to a specified URL.

    where:

    post <url> (required)

    Specifies the URL for data metrics update.

    delay <u>

    <u> Specifies the period between each attempt to send new data metrics. The delay keyword is a simplified version of the xdelay keyword.

    xdelay <u s b r>

    Delay settings are defined as follows:

    • <u> specifies the period between each attempt to send new data metrics. If the module cannot send the metrics data after three attempts, it cancels the update until the next time interval defined by <u>. Default: 60m

    • <s> specifies the initial (first) delay to send the data. Default: 5s

    • <b> parameter is not used in this module and its value is not important. It is present only because of the compatibility of xdelay parameters with other lb-update-like modules. Default: 10s

    • If the data fails to send, <r> determines the delay for the next attempt. Default: 5s

    timeout <t>

    Specifies the HTTP connection timeout for attempts to send new data metrics. The value is in milliseconds by default, but you can set it to any other unit if you add it as a suffix to the number. Default: 5s

    retries <n>

    Specifies number of retries to send new data metrics. If unspecified, HAProxy uses the global retries value. Default: 3s

    log

    Specifies whether to log operation errors.

    dontlog-normal

    Deactivates logging for successful updates.

    param*

    A list of other server line parameters for HAProxy. This is useful for configuring special SSL features. This includes ca-file, verify [none|optional|required], etc.

  • send-metrics-data <data> (required): Data to send to the selected HTTP server. You can set individual log variables within the data (prefixed with %).

  • send-metrics-content-type <content-type>: Allows the module to set the "Content-Type" header when sending data, including and limited to the content types listed below. If unspecified, the module uses the "application/octet-stream" Content-Type.

    Supported content types are:

    • application/json

    • application/octet-stream

    • application/x-www-form-urlencoded

    • text/plain

  • send-metrics-debug <level>: Sets the debug level. Use this only when the module runs in debug mode; in normal use it has no significance. Default: level 7.

  • send-metrics-header <header> [header]...: Allows the module to set additional HTTP headers within the HTTP POST request.

HAProxy Runtime API

The following Runtime API commands are available:

lb-send-metrics debug [level]

Sets the debug level. Sets the debug level. You can use this only when the module runs in debug mode; in normal use it has no significance. Default: level 7.

lb-send-metrics show-data

Serves to check the operation of the module by printing the content similar to the one that the module sent to the selected HTTP server.

lb-send-metrics status

Displays the module's status.

lb-send-metrics update [delay]

Runs the update at a time specified with the delay setting. If unspecified (or the delay is 0), the update executes immediately. The delay cannot exceed the time until the next regular update.

Example configuration

The following is an example configuration for the Send Metrics module:

global
    nbthread 64
    hard-stop-after 10s
    log localhost:514 local7 debug
    ssl-server-verify none
    debug
    stats socket /tmp/haproxy.sock mode 666 level admin

    module-load send-metrics.so
    send-metrics-debug 127
    send-metrics-url POST http://localhost:8000/v1/feed/__SourceUUID__  xdelay 1m 5s 1s 1s  timeout 100ms  retries 3  log
    #   send-metrics-url POST https://localhost:8443/v1/feed/__SourceUUID__  xdelay 1m 5s 1s 1s  timeout 5s  retries 3  log ca-file <path-to-ca>
    send-metrics-header 'X-NSONE-Key: __APIKey__' 'X-Send-Metrics: 42'
    send-metrics-content-type application/json
    send-metrics-data '{ "lga01": { "Hostname": "%H", "Date": "%T", "connections": "%ac" } }'

defaults
    log     global
    mode    http
    option  httplog
    option  dontlognull
    retries 3
    timeout connect 5000
    timeout client  50000
    timeout server  50000

listen Send-Metrics-module-test
    bind *:10080
    mode http
    server localhost 127.0.0.1:8000

    option http-buffer-request
    declare capture request len 40000
    http-request capture req.body id 0