Use the HAProxy Enterprise OpenTelemetry module

HAProxy Enterprise’s OpenTelemetry module enables you to collect traffic data and use it to generate traces, metrics, and logs. Through the OpenTelemetry protocol, which many software products implement, you can export that data to a number of third-party solutions that let you visualize how traffic is flowing through the load balancer. Use the information to spot bottlenecks and to correlate one signal with another, such as to connect log records with traces.

On this page, you’ll learn how to install the module. Then, follow up with steps for customizing which events to monitor and where to send the data.

Install the OpenTelemetry module Jump to heading #

1. Install the OpenTelemetry module according to your platform:

   Install the OpenTelemetry module

   Install the OpenTelemetry module3.4r13.3r13.2r1

   apt yum zypper pkg

   nix
   sudo apt-get install hapee-3.4r1-lb-opentelemetry

   nix
   sudo apt-get install hapee-3.4r1-lb-opentelemetry

   nix
   sudo yum install hapee-3.4r1-lb-opentelemetry

   nix
   sudo yum install hapee-3.4r1-lb-opentelemetry

   nix
   sudo zypper install hapee-3.4r1-lb-opentelemetry

   nix
   sudo zypper install hapee-3.4r1-lb-opentelemetry

   nix
   sudo pkg install hapee-3.4r1-lb-opentelemetry

   nix
   sudo pkg install hapee-3.4r1-lb-opentelemetry

   apt yum zypper pkg

   nix
   sudo apt-get install hapee-3.3r1-lb-opentelemetry

   nix
   sudo apt-get install hapee-3.3r1-lb-opentelemetry

   nix
   sudo yum install hapee-3.3r1-lb-opentelemetry

   nix
   sudo yum install hapee-3.3r1-lb-opentelemetry

   nix
   sudo zypper install hapee-3.3r1-lb-opentelemetry

   nix
   sudo zypper install hapee-3.3r1-lb-opentelemetry

   nix
   sudo pkg install hapee-3.3r1-lb-opentelemetry

   nix
   sudo pkg install hapee-3.3r1-lb-opentelemetry

   apt yum zypper pkg

   nix
   sudo apt-get install hapee-3.2r1-lb-opentelemetry

   nix
   sudo apt-get install hapee-3.2r1-lb-opentelemetry

   nix
   sudo yum install hapee-3.2r1-lb-opentelemetry

   nix
   sudo yum install hapee-3.2r1-lb-opentelemetry

   nix
   sudo zypper install hapee-3.2r1-lb-opentelemetry

   nix
   sudo zypper install hapee-3.2r1-lb-opentelemetry

   nix
   sudo pkg install hapee-3.2r1-lb-opentelemetry

   nix
   sudo pkg install hapee-3.2r1-lb-opentelemetry

   Installing the module creates these files in the /etc/hapee-<VERSION>/ directory:

   • instrumentation.cfg: The instrumentation file is where you define the load balancer events to include in OpenTelemetry traces, metrics, and logs. This file defines some default settings, which you can customize.
   • otel-client.yaml:The client library configuration file controls the underlying OpenTelemetry C++ client, which is responsible for batching and exporting metrics, traces, and logs to a remote endpoint where the data can be processed and displayed.

2. In your load balancer configuration, update the global section to have a module-load directive. Set its value to hapee-lb-opentelemetry.so.

   hapee-lb.cfg
   haproxy
   global
     ...
     module-load hapee-lb-opentelemetry.so

   hapee-lb.cfg
   haproxy
   global
     ...
     module-load hapee-lb-opentelemetry.so

3. Update your frontend section to have a filter opentelemetry directive. This enables instrumentation, which you’ll configure with the file instrumentation.cfg. The filter opentelemetry directive has these arguments:

   • id sets a unique identifier for this filter.
   • config indicates the path to the instrumentation file.
   Add an OpenTelemetry filter

   Add an OpenTelemetry filter3.4r13.3r13.2r1

   hapee-lb.cfg
   haproxy
   frontend myfrontend
     ...
     filter opentelemetry id my-otel-filter config /etc/hapee-3.4/instrumentation.cfg 

   hapee-lb.cfg
   haproxy
   frontend myfrontend
     ...
     filter opentelemetry id my-otel-filter config /etc/hapee-3.4/instrumentation.cfg 

   hapee-lb.cfg
   haproxy
   frontend myfrontend
     ...
     filter opentelemetry id my-otel-filter config /etc/hapee-3.3/instrumentation.cfg 

   hapee-lb.cfg
   haproxy
   frontend myfrontend
     ...
     filter opentelemetry id my-otel-filter config /etc/hapee-3.3/instrumentation.cfg 

   hapee-lb.cfg
   haproxy
   frontend myfrontend
     ...
     filter opentelemetry id my-otel-filter config /etc/hapee-3.2/instrumentation.cfg 

   hapee-lb.cfg
   haproxy
   frontend myfrontend
     ...
     filter opentelemetry id my-otel-filter config /etc/hapee-3.2/instrumentation.cfg 

4. Reload the HAProxy Enterprise configuration to apply the changes.

   Reload HAProxy Enterprise

   Reload HAProxy Enterprise3.4r13.3r13.2r1

   nix
   sudo systemctl reload hapee-3.4-lb

   nix
   sudo systemctl reload hapee-3.4-lb

   nix
   sudo systemctl reload hapee-3.3-lb

   nix
   sudo systemctl reload hapee-3.3-lb

   nix
   sudo systemctl reload hapee-3.2-lb

   nix
   sudo systemctl reload hapee-3.2-lb

Next steps Jump to heading #

After installing the OpenTelemetry module, here’s what to do next:

• Set up OpenTelemetry Collector for testing: The otel-client.yaml file is configured to send OpenTelemetry data to the load balancer’s own address, http://localhost:4318. For testing, you can run OpenTelemetry Collector there. Or, edit the file and send data to a different destination, such as your own OpenTelemetry Collector, Jaeger, or other software.

• Read the HAProxy OpenTelemetry tutorials to learn how to configure logs, metrics, and traces.