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.

Install Send Metrics

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

    apt install hapee-1.8r1-lb-send-metrics

    or

    yum install hapee-1.8r1-lb-send-metrics

Configure Send Metrics

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

    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