HAProxy Enterprise Documentation 2.5r1

Traffic Mirroring Reference

The SPOE mirror engine uses Stream Processing Offload Protocol (SPOP). The file /etc/hapee-extras/hapee-mirror-spoe.cfg configures how HAProxy Enterprise communicates with the SPOE mirror agent.

[mirror]
spoe-agent mirror
    log global
    messages mirror
    use-backend mirroragents
    timeout hello 500ms
    timeout idle 5s
    timeout processing 5s

spoe-message mirror
    args arg_method=method arg_path=url arg_ver=req.ver arg_hdrs=req.hdrs_bin arg_body=req.body
    event on-frontend-http-request

It supports the following directives in the spoe-agent section:

Parameter

Description

[*name*]

The file begins with an engine name, mirror, in square brackets. As mentioned, this name must match the engine parameter value set on the filter spoe directive in the HAProxy Enterprise configuration.

log global

This line means that events, such as when HAProxy Enterprise sends data, will be logged to the same output defined by the log statement in the global section of the HAProxy Enterprise configuration.

messages

This line is a space-delimited list of labels that match up with spoe-message sections.

use-backend

This line specifies which backend in the HAProxy Enterprise configuration holds the mirror agents.

timeout hello
This setting limits how long HAProxy Enterprise will wait for an agent to

acknowledge a connection.

timeout idle

This setting limits how long HAProxy Enterprise will wait for an agent to close an idle connection.

timeout processing

This setting limits how long an agent is allowed to process an event.

A spoe-message section defines which HAProxy Enterprise fetch methods will be used to capture data to send to the agents. The label here, mirror, is expected by this particular agent. For traffic mirroring, we capture the following:

  • the HTTP method

  • the URL path

  • the version of HTTP

  • all HTTP headers

  • the request body (note that this requires option http-buffer-request in the HAProxy Enterprise configuration)

Data is sent every time the on-frontend-http-request event fires, which is before the evaluation of http-request rules on the frontend side.

The options supported by hapee-spoa-mirror can be found using -h or --help:

$ /opt/hapee-extras/bin/hapee-spoa-mirror -h
Usage: hapee-spoa-mirror { -h --help }
    hapee-spoa-mirror { -V --version }
    hapee-spoa-mirror { -r --runtime=TIME } [OPTION]...


Options are:
-a, --address=NAME              Specify the address to listen on (default: "0.0.0.0").
-B, --libev-backend=TYPE        Specify the libev backend type (default: AUTO).
-b, --connection-backlog=VALUE  Specify the connection backlog size (default: 10).
-c, --capability=NAME           Enable the support of the specified capability.
-D, --daemonize                 Run this program as a daemon.
-F, --pidfile=FILE              Specifies a file to write the process-id to.
-h, --help                      Show this text.
-i, --monitor-interval=TIME     Set the monitor interval (default: 5.00s).
-l, --logfile=[MODE:]FILE       Log all messages to logfile (default: stdout/stderr).
-m, --max-frame-size=VALUE      Specify the maximum frame size (default: 16384 bytes).
-n, --num-workers=VALUE         Specify the number of workers (default: 10).
-p, --port=VALUE                Specify the port to listen on (default: 12345).
-r, --runtime=TIME              Run this program for the specified time (0 = unlimited).
-t, --processing-delay=TIME     Set a delay to process a message (default: 0).
-u, --mirror-url=URL            Specify the URL for the HTTP mirroring.
-I, --mirror-interface=NAME     Specify the interface/address for outgoing connections.
-P, --mirror-local-port=VALUE   Specify the local port range for outgoing connections.
-V, --version                   Show program version.

Supported libev backends: select, poll, epoll, linuxaio, iouring.

Supported capabilities: fragmentation, pipelining, async.

Allowed logging file opening modes: a, w. The a mode allows opening or creating file for writing at end-of-file. The w mode allows truncating the file to zero length or creating a new file. If a capital letter is used for the mode, then line buffering is used when writing to the log file.

The time delay/interval is specified in milliseconds by default, but can be in any other unit if the number is suffixed by a unit (us, ms, s, m, h, d).

Traffic Mirroring Log Reference

SPOE mirror agent activity is logged using HAProxy Enterprise's logger. Mirrored requests are logged to the file /var/log/hapee-2.5/lb-access-<date>.log by default. A message is emitted for each mirrored request. Depending on the status code, the log level will be different. In the normal case, when no error occurred, the message is logged with the level LOG_NOTICE. If an error occurred, the message is logged with the level LOG_WARNING.

Consider the following example log message for a mirrored request:

An example log statement is shown below:

Aug 25 17:48:36 node1 hapee-lb[215242]: SPOE: [mirror] <EVENT:on-frontend-http-request> sid=707 st=0 0/13/8/0/22 1/1 0/0 0/1

In this example, the mirror agent logged an event named on-frontend-http-request with a stream-id of 707. Its status code of 0 indicates it was successful. One event was processed and had zero errors.

Mirror agent log messages follow this format:

SPOE: [AGENT] <TYPE:NAME> sid=STREAM-ID st=STATUS-CODE reqT/qT/wT/resT/pT <idles>/<applets> <nb_sending>/<nb_waiting> <nb_error>/<nb_processed>

Log Message Item

Description

AGENT

The agent name. It is mirror for the mirror agent.

TYPE

For mirrored requests this is EVENT.

NAME

The event name.

STREAM-ID

The unique integer id of the stream.

STATUS_CODE

The request's status code. A status code of 0 indicates success. Other status codes include:

  • 1: I/O error.

  • 2: A timeout occurred.

  • 3: Frame is too big.

  • 4: Invalid frame received.

  • 5: Version value not found.

  • 6: max-frame-size value not found.

  • 7: Capabilities value not found.

  • 8: Unsupported version.

  • 9: max-frame-size too big or too small.

  • 10: Payload fragmentation is not supported.

  • 11: Invalid interlaced frames.

  • 12: frame-id not found (it does not match any referenced frame).

  • 13: Resource allocation error.

  • 99: An unknown error occurred.

reqT/qT/wT/resT/pT

These represent the following time events:

  • reqT : The encoding time. It includes ACLs processing time, if applicable. For fragmented frames, it is the sum of all fragments.

  • qT : The delay before the request leaves the sending queue. For fragmented frames, it is the sum of all fragments.

  • wT : The delay before the response is received. Fragmentation is not supported.

  • resT : The delay in processing the response. Fragmentation is not supported.

  • pT : The delay in processing the event; it is the latency added by the SPOE processing. It is more or less the sum of the other values.

<idle>

The number of idle SPOE applets.

<applets>

The number of SPOE applets.

<nb_sending>

The number of streams waiting to send data.

<nb_waiting>

The number of streams waiting for an ack.

<nb_error>

The number of processing errors.

<nb_processed>

The number of events processed.

Next up

Security