Monitor HAProxy with OpenTelemetry

Osuite monitors HAProxy through the OpenTelemetry Collector’s haproxy receiver, which reads HAProxy’s statistics (CSV) output and exports connection, request, and response metrics over OTLP. They share resource attributes with your services, so a spike in denied or errored requests lines up with the traffic behind the proxy.

Note

The haproxy receiver ships in the Collector contrib distribution. Use otelcol-contrib (or any build that includes it), not the core otelcol binary.

Setup

Prerequisites

The receiver’s endpoint is either a local stats socket or an HTTP stats URL. Expose one of them in haproxy.cfg.

For a Collector on the same host, enable the stats socket:

global
    stats socket /var/run/haproxy.ipc mode 660 level admin

For a Collector in a separate container or pod, expose the HTTP stats page:

frontend stats
    bind *:8404
    stats enable
    stats uri /stats

Reload HAProxy after editing the configuration.

Configure the Collector

1. Add the haproxy receiver, the otlp/osuite exporter, and a metrics pipeline. Use the socket path when the Collector shares the host; use the HTTP stats URL otherwise. Pick the tab that matches where your Collector runs.

   Bare host

   receivers:
     haproxy:
       endpoint: file:///var/run/haproxy.ipc
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [haproxy]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

   Docker

   receivers:
     haproxy:
       endpoint: http://haproxy:8404/stats
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [haproxy]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

   Kubernetes

   receivers:
     haproxy:
       endpoint: http://haproxy.default.svc.cluster.local:8404/stats
       collection_interval: 30s
   
   processors:
     batch:
     resourcedetection:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [haproxy]
         processors: [batch, resourcedetection]
         exporters: [otlp/osuite]

2. Start the Collector. On Docker and Kubernetes, the Collector and HAProxy must share a network so the endpoint resolves.

Validate

What you should see

Metrics named haproxy.* appear in Dashboards → Explore metrics within a minute, broken down by proxy and server.

Data collected

Metric	Description	Unit
haproxy.requests.total	Total HTTP requests received	{requests}
haproxy.requests.rate	HTTP requests over the last second	{requests}
haproxy.requests.errors	Cumulative request errors	{errors}
haproxy.requests.denied	Requests denied for security reasons	{requests}
haproxy.requests.queued	Requests currently queued	{requests}
haproxy.requests.redispatched	Requests rerouted to another server	{requests}
haproxy.connections.rate	Connections over the last second	{connections}
haproxy.connections.errors	Connection errors to backend servers	{errors}
haproxy.bytes.input	Bytes received	By
haproxy.bytes.output	Bytes sent	By

Dashboards and alerts

Once metrics arrive, build an HAProxy dashboard in the dashboard builder from the series above. Alerts in Osuite are PromQL-based — see Alerts. Useful starting conditions: rising haproxy.requests.errors, a growing haproxy.requests.queued, and haproxy.connections.errors to backends.

Troubleshooting

• Permission denied on the socket — confirm the socket mode/level grants access and that the Collector process can read /var/run/haproxy.ipc.
• Empty or refused HTTP stats — confirm the stats frontend is bound and reachable, and that the endpoint points at the stats path.

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.