Using a hosted Web application

The Real-Time Dashboard is a Web interface that does not require any installation.

Users with a valid HAProxy Technologies Customer Portal account have immediate access to the Real-Time Dashboard:

1. Go to http://dashboard.haproxy.com/.

2. See the section below on Set up Real-Time Dashboard module.

Serving Real-Time Dashboard locally

1. Install the hapee--lb-dashboard package on the host with your Web server.

2. Set up a minimal Web server to serve static files anywhere on your network.

3. Locate the Web server's "document root" (usually /var/www/html/)

4. Create a shortcut (symlink) or copy the files from the directory /opt/hapee-/dashboard/dashboard/ to the Web server's document root sub-directory dashboard/, as follows:

   cd /var/www/html
   
   # Symlink (preferred)
   ln -sf /opt/hapee-*/dashboard/dashboard .
   
   # Copy
   cp -a /opt/hapee-*/dashboard/dashboard .

5. Access the Real-Time Dashboard at http://web.server.address/dashboard/index.html.

6. Configure HAProxy instances to respond to requests coming from Real-Time Dashboard (see below).

Prerequisites

• HAProxy Enterprise version >= 1.7 on all HAProxy Enterprise instances within the in the cluster

• HAProxy Enterprise Dashboard Module v0.9 or higher must be installed and configured on all instances.

Set up an aggregation cluster

To set up a new aggregation cluster:

• If you are in "Single Node" data source mode: click on to display the "Cluster Setup" window.

• If you are in "Cluster Aggregation" data source mode, click on the right side of the "Cluster Overview" pane to display the "Cluster Setup" window.

The current Real-Time Dashboard instance becomes the new master node by default. You can set a different node the "Master Node" box.

1. Enter the cluster nodes IPs in the boxes. The nodes displayed in the setup window come from the configuration of the master node.

2. If necessary, click to add more nodes, or to delete them.

3. Click "Create Cluster". When successful, a green check mark appears next to the node; if not, a red X appears.

4. Click "Use Cluster" to switch Real-Time Dashboard to work in cluster mode.

Initialize an aggregation cluster

There are three different ways in which you can initialize an aggregation cluster, using:

• A declarative configuration with the dashboard-config.lua file

• The Dashboard Cluster Setup window (see below)

• The JSON RESTful API of the Dashboard Module, or Dashboard Gateway.

After you bring up all the instances, you instantiate the Master Node by passing it the list of nodes in a JSON array of strings containing the IP:port pairs to the /cluster/nodes endpoint with a PUT request.

For example, a cluster that includes the following nodes:

The JSON array sent to the Master Node looks like the following:

[
    "127.0.0.1:9022",
    "127.0.0.2:9122",
    "127.0.0.3:9222"
]

Using curl and the following parameters:

• Master node: 127.0.0.1:9022

• User name and password: dashboard:test (Basic Authorization configured in Real-Time Dashboard configuration file /etc/hapee-/dashboard-module.cfg).

• Request Content-Type: application/json

  curl -XPUT -s -u dashboard:test 127.0.0.1:9022/cluster/nodes \
       -H "Content-Type: application/json" \
       -d '["127.0.0.1:9022", "127.0.0.2:9122", "127.0.0.3:9222"]'

The master node solicits acknowledgment from the other nodes, and it returns a list of all nodes with available stats with a host:port and HTTP status code like the following:

{"127.0.0.1:9022":201, "127.0.0.2:9122":201, "127.0.0.3:9222":201}

• If the requests are successful, the status codes indicate 201.

• The master node retains only the nodes that were successfully added in its state and collects their data.

  Tip

  You can perform a GET request from the same endpoint /cluster/nodes to get a list of nodes added to the aggregation cluster in JSON array form, e.g. ["127.0.0.1:9022", "127.0.0.2:9122", "127.0.0.3:9222"]

• The Master Node receives and returns its own IP:port. This is necessary, but it does not have to be the first entry in the array.

Add/delete nodes

You can add and/or delete nodes from aggregation performing a PUT request for a different array of nodes to the /cluster/nodes endpoint in the master node. The change takes effect in Real-Time Dashboard when it gets the next cluster data response with the new list of nodes.

Stop aggregation

You can stop aggregation on the Master Node by performing a PUT request for an empty tray. The node ceases to be the master node.

Configure the Declarative module

A Lua configuration file (dashboard-config.lua) comes with the package. The default configuration is effectively empty for single instance usage.

The file uses Lua table syntax, and can configure the following options:

conf = {
  admin_commands = true,   -- whether or not to execute admin commands, default: true
  cron_interval = 1000,    -- caching interval, default: 1000
  max_payload_size = 8192, -- maximum allowed input payload, default: 8192

  cluster = {
    master = true,         -- is the node a Cluster Aggregation Master? default: false
    nodes = {              -- list of Aggr. Cluster nodes, empty by default
      "127.0.0.1:9022",    --   the node format is "IP:PORT"
      "127.0.0.2:9023",
      ...
    }
  }
}

Set up aggregation clusters for multiprocesses

When you set up HAProxy in multiprocsses mode (e.g by setting the nbproc option to an integer value larger than 1), each process has its own statistics that require aggregation with the Cluster Aggregation mode.

To enable cluster aggregation, the Dashboard module must listen on a different bind for each process.

1. Edit the file dashboard-module.cfg and replace the default bind line:

   listen dashboard
     bind *:9022

   with something like this:

   listen dashboard
     bind *:9022 process 1   # this is your master node
     bind *:9122 process 2
     bind *:9222 process 3
     bind *:9322 process 4   # assuming nbproc 4

2. To allow the master process to aggregate statistics from your other processes, edit the file dashboard-config.lua to match these settings:

   conf = {
     admin_commands = true,
   
     cluster = {
       master = true,         -- set the module to cluster master mode
       nodes = {
         "127.0.0.1:9022",    -- each node represent a separate bind line from the
         "127.0.0.2:9122",    -- dashboard-module.cfg above
         "127.0.0.2:9222",
         "127.0.0.2:9322"
       }
     }
   }

   Now you can monitor aggregated statistics for your instance using the Real-Time Dashboard.

Aggregation Cluster and Stick Table Aggregator

Real-Time Dashboard also works with the Stick Table Explorer to enable you to explore the contents of HAProxy Stick Tables in your instance(s).

The aggregation cluster mode assumes that the Stick Table Aggregator (hapee-stktagg) aggregates stick tables across the same set of instances, and that the master node instance uses aggregated stick tables from the Stick Table Aggregator.

Local tables used for aggregation have the suffix .local, and resulting aggregated tables have the suffix with .aggr (modifiable in General Settings).

Apart from setting up the aggregation cluster and editing table suffixes as necessary, there is no additional setting to configure in Real-Time Dashboard.

Header bar

Located at the top of the screen, the header bar allows you to perform the following tasks:

Reload the page

Click on the HAProxy Logo (1)

Enter the address of the HAProxy instance

In the URL Box (2), use a format similar to [<http|https>://]domain|IP[:port][/path]

Note

• The mandatory information is the domain name or IP address of the HAProxy instance. It defaults to the domain where the UI is hosted.

• You can omit http or https because this information is stored

• If you do not specify a port, Real-Time Dashboard uses the default port

• If you enter a path, Real-Time Dashboard appends the standard API endpoints ("/dashboard" or "/cluster") to it

• The icon indicates whether the access to the HAProxy instance uses TLS encryption. This is a toggle function.

  • If you connect to Real-Time Dashboard over HTTPS, you cannot connect to a HAProxy instance with an unencrypted link; hence the toggle is disabled.

  • If you connect to a HAProxy instance over HTTPS, we recommend that you use a valid SSL certificate. Invalid certificates (not trusted by the browser) cause Javascript calls to fail silently and return a "Request Error" message when you click on "Servers Status".

Turn on or off data fetching

Click on the Start/Stop button (3). If you set the data refresh interval to "Off" in "Settings", you can display an instantaneous update by clicking "Refresh".

Display the overview

Click on Overview button (4)

Display the cluster overview

Click on Cluster button (5) Available only in Cluster Aggregation mode. In Single Mode, it displays the Cluster Setup Dialog (see below).

Display statistics

Click on Stats button (6)

Display stick tables

Click on Stick button (7)

Configure the Real-Time Dashboard

Click Settings (8) to display configuration options

Info Bar

The Info Bar contains general information about an instance. In Cluster Aggregation mode, it displays instances to which the Real-Time Dashboard is connected.

When in Cluster Aggregation mode, the main view of the Info Bar displays aggregated information; to drill down to information for each instance, click the icon.

The Info bar gives the following information:

Overview

The Overview window is the initial view of the application. It displays the instance-level (or cluster-level) summarized information, as well as key metric charts.

It contains the following elements:

HTTP Request Rate Chart (1)

Charts the total HTTP request rate across the instance (or across all instances in Cluster Mode).

HTTP Error Rate Chart (2)

Charts the total HTTP error rate across the instance (or across all instances in Cluster Mode).

Average Response Time Chart (3)

Charts the average response time across the instance (or across all instances in Cluster Mode).

HTTP Requests Panel (4)

Displays the instance-level (or aggregate) HTTP Request related stats and limits.

SSL Connections Panel (5)

Displays the instance-level (or aggregate) SSL Connection related stats and limits.

TCP Connections Panel (6)

Displays the instance-level (or aggregate) TCP Connection related stats and limits.

Overview Charts

The Overview graphs display information for HTTP traffic, average response time, and SSL/TCP connections.

Zoom Level Selector (1)

Sets five different zoom levels for the Main Chart Display (30 seconds, 1 minute, 3 minutes, 10 minutes, and 30 minutes) The zoom level is synchronized across all three Overview Graphs.

Main Chart Display (2)

A tool tip appears when hovering over any chart point to show the detailed data point (time and value). This data point is synchronized across all three Overview Charts.

Time Axis (3)

Horizontal axis is the data point event time axis

Value Axis (4)

Vertical axis is the data-point values axis

Chart Navigator (5)

Displays the local data history in a miniature view with its own time axis.

Navigator Handles (6)

Focuses on a time period in the local history when you drag the handles. When you release the handle, the selected zoom level/period is synchronized across the three Overview Charts.

Stats Pane

The Stats Pane presents individual Proxy (frontend, backend or listen block) statistics, as well as individual Server statistics in a table view.

The Stats Pane consists of the following major sections:

Filter Block (1)

See Set filter criteria

Quick Navigation buttons (2)

Gives quick access to the selected Proxy on the screen.

Stats Tables (3)

Proxy and Server statistics, see Stats Pane under Data Fields for more detailed data on statistics values.

Quick Action Buttons (4)

See below

Stats Table

The tables operate slightly differently depending on the Data Source Mode:

• Single Node: Each server appears on one line, and its statistics and status come from the instance to which Real-Time Dashboard is connected.

• Cluster Aggregation: Each server appears as a header line in gray with statistics and status aggregated across all the nodes that it contains.

Depending on the mode, Stats tables display the following information:

Proxy Name

Real-Time Dashboard infers from available server lines whether the block is a frontend, backend, or listen (or FE/BE pair with same name, which it treats as a listen block).

Server Names

Name of the server

Statistics Columns

Hover over each column heading to display additional information. If the server state is not up, the entire row takes on the Server State color, as used for Filter Block labels. See "Stats Pane" in the section Understanding data from Real-Time Dashboard for more detailed data on statistics values.

Select filter

You can set filters in the following ways:

• Text - Allows filtering by Frontend or Backend Name (i.e. Proxy name) or by Server Name. There are three modes of filtering:

  • Partial String Matching: For example, when you enter "ss", it matches up with "blessing", "pass", or "sserver".

  • Multi-String Partial Matching: For example, when you enter "we se" it matches up with "webserver", "awesome_service" and "we_base".

  • RegEx Matching: For example, when you enter a string that begins and ends with a forward slash ("/") it matches only those strings that a regular expression between those two slashes would match. The precise regular expression syntax used is JavaScript Regular Expressions.

• Server Status - Allows filtering by server status. A click on any server status toggles its state between selected and unselected.

Use filter for administrative tasks

For a list of administrative tasks, see the section on how to Manage servers.

Reset filter

• Click to restore the filter to default state (all Proxies/Servers visible); this function is enabled only when filter is active.

Hide filter

• Click to collapse the filter block (to free up vertical screen space).

Retrieve a stick table

1. Click on in the header bar to display the Stick Table Explorer.

2. Select a table from a drop-down list (1).

3. Filter out some unwanted data by clicking (2) and specifying the filter criteria. Toggling this button shows or hides the filter.

4. Click (3) to retrieve the following stick table information (4):

   • Type - type of key

   • Length - number of table columns

   • Expires - how long a row is kept in the table before it expires

   • Purge - whether the table purges old elements

   • Size - maximum number of rows

   • Used - current number of rows

Apply filters

You can filter table data in two stages:

• Globally, prior to instance retrieval (5): Real-Time Dashboard retrieves data on the HAProxy instance itself according to the filtering criteria (up to four maximum)

• Locally, in the browser (6): In contrast to the global filter which occurs on the HAProxy instance itself, the local filter happens within the browser. When you remove a criterion, the table refreshes accordingly; however, it has no effect on the amount data retrieved from the instance.

You can combine the two filters to limit the data retrieved and refine the data to display within the browser.

Export CSV

• Click (7) to download the entire table in CSV format.

  Note

  All data gets exported to CSV, regardless of any filter previously set.

Navigate between pages

1. Click on the page number (8) or << and >> to switch pages.

2. Choose the number of items to display: 10, 25, or 50.

Sort data

• Click on the up or down arrow next to the column header to sort data by ascending or descending order.

Overview Pane

The "Overview" pane displays general and summarized real-time information about the HAProxy instance.

Stats Pane

The "Stats" pane displays detailed real time information about the HAProxy frontends and backends, and allows you to perform management actions on servers.

Perform an action on server(s)

1. Select a server by clicking on the checkbox next to its name. To select all servers in a block, click the checkbox next to the block name.

2. Select a task from the drop-down list (see below).

3. Click "Apply".