Integrate OpenTelemetry with Instana for HAProxy

You can use OpenTelemetry support of HAProxy with IBM Instana® Observability.

HAProxy is a third‑party open source component. Open source communities or vendors maintain this HAProxy OpenTelemetry filter. Instana® supports the integration of the HAProxy OpenTelemetry filter with Instana for distributed tracing observability. HAProxy configuration, upstream code, and general support are outside the scope of Instana. For HAProxy documentation and support, refer to the HAProxy documentation.

Important:
HAProxy support for OpenTelemetry is not yet generally available (GA) and is currently in alpha. This integration is tested against the same alpha version of the HAProxy OpenTelemetry filter.

Supported operating systems

Instana supports OpenTelemetry integration on Linux operating systems only.

Prerequisites

To integrate OpenTelemetry with Instana, you need the following components:

  • HAProxy version 3.4 or later, built with the HAProxy OpenTelemetry filter
  • The HAProxy OpenTelemetry filter (haproxy‑opentelemetry) built against the OpenTelemetry C Wrapper library version 2.2.0 or later
  • An active IBM Instana Observability account

Overview

The OpenTelemetry filter generates telemetry data from HAProxy, and the Instana Distribution of OpenTelemetry Collector (IDOT) forwards that data to Instana.

Building HAProxy with the OpenTelemetry filter

HAProxy does not include the OpenTelemetry filter by default. To use OpenTelemetry tracing, you must build HAProxy with the HAProxy OpenTelemetry filter (haproxy‑opentelemetry).

For detailed build instructions and a complete Docker image build reference, see the HAProxy README in the example repository.

Configuring HAProxy with OpenTelemetry

The HAProxy OTel filter uses a two‑file configuration model:

Table 1. HAProxy OpenTelemetry configuration files
Configuration file Purpose
OTel configuration file (.cfg) Defines the telemetry model, including instrumentation settings, scopes, groups, spans, attributes, metrics, and log records.
YAML configuration file (.yml) Defines the OpenTelemetry SDK pipeline, including exporters, samplers, processors, providers, and signal routing.

Trace context propagation

The HAProxy OTel filter uses the W3C Trace Context standard for distributed tracing. It propagates trace context by using the following standard HTTP headers:

  • traceparent: Contains the trace ID, parent span ID, and trace flags

The filter does not support Instana‑specific headers for trace propagation:

  • X-Instana-T (Trace ID)
  • X-Instana-S (Span ID)
  • X-Instana-L (Sampling level or decision)

If a downstream service uses Instana‑native header propagation, you can strip those headers in the HAProxy configuration to force the Instana agent on the downstream service to read traceparent only:

http-request del-header X-INSTANA-T
http-request del-header X-INSTANA-S
http-request del-header tracestate

Integrating the OpenTelemetry collector

To integrate OpenTelemetry with Instana, use the IBM Instana Distribution of OpenTelemetry Collector (IDOT).

IDOT is a fully managed and preconfigured version of the OpenTelemetry Collector that seamlessly integrates with the Instana observability platform.

For configuration details and examples, see the HAProxy OpenTelemetry tracing.

To configure the integration with the OpenTelemetry Collector, see Configuring the OpenTelemetry Collector.

Infrastructure correlation

The service.name resource attribute in the YAML provider configuration is used for infrastructure correlation, which links your HAProxy application traces with the underlying infrastructure entities (hosts, containers, Kubernetes pods, and processes) that are monitored by Instana.

When you set service.name, Instana uses this service name to complete the following tasks:

  • Correlate HAProxy traces with infrastructure metrics (CPU, memory, and network)
  • Map service dependencies and call relationships
  • Enable bidirectional navigation between application and infrastructure views
  • Provide complete context for root cause analysis

For more information about infrastructure correlation and OpenTelemetry integration, see the following topics: